espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-07-30 18:57:19 +02: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

2
components/esp_wifi/test/test_phy_rtc.c
View File

@ -13,7 +13,7 @@
#include <freertos/semphr.h>
#include "soc/soc_caps.h"
#if !TEMPORARY_DISABLED_FOR_TARGETS(ESP32S2)
#if !TEMPORARY_DISABLED_FOR_TARGETS(ESP32S2, ESP32C3)
//Function just extern, need not test
#if SOC_BT_SUPPORTED

10
components/hal/include/hal/adc_types.h
View File

@ -142,7 +142,7 @@ typedef struct {
uint8_t reserved: 2; /*!< reserved0 */
#endif
};
uint8_t val;
uint8_t val; /*!<Raw data value */
};
} adc_digi_pattern_table_t;
@ -193,14 +193,14 @@ typedef struct {
union {
struct {
uint32_t data: 12; /*!<ADC real output data info. Resolution: 12 bit. */
uint32_t reserved12: 1;
uint32_t reserved12: 1; /*!<Reserved12. */
uint32_t channel: 3; /*!<ADC channel index info.
If (channel < ADC_CHANNEL_MAX), The data is valid.
If (channel > ADC_CHANNEL_MAX), The data is invalid. */
uint32_t unit: 1; /*!<ADC unit index info. 0: ADC1; 1: ADC2. */
uint32_t reserved17_31: 15;
} type2;
uint32_t val;
uint32_t reserved17_31: 15; /*!<Reserved17. */
} type2; /*!<When the configured output format is 12bit. `ADC_DIGI_FORMAT_11BIT` */
uint32_t val; /*!<Raw data value */
};
} adc_digi_output_data_t;
#endif

2
components/soc/esp32c3/include/soc/soc_caps.h
View File

@ -8,7 +8,7 @@
#define SOC_CPU_CORES_NUM 1
#define SOC_GDMA_SUPPORTED 1
#define SOC_TWAI_SUPPORTED 1
#define SOC_BT_SUPPORTED 1
// There are 3 DMA channels on ESP32-C3
// Attention: These fixed DMA channels are temporarily workaround before we have a centralized DMA controller API to help alloc the channel dynamically

2
docs/build_docs.py
View File

@ -39,7 +39,7 @@ from collections import namedtuple
from packaging import version
LANGUAGES = ['en', 'zh_CN']
TARGETS = ['esp32', 'esp32s2']
TARGETS = ['esp32', 'esp32s2', 'esp32c3']
SPHINX_WARN_LOG = 'sphinx-warning-log.txt'
SPHINX_SANITIZED_LOG = 'sphinx-warning-log-sanitized.txt'

18
docs/conf_common.py
View File

@ -161,17 +161,22 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst',
'api-guides/unit-tests-legacy.rst',
'get-started-legacy/**']
USB_DOCS = ['api-reference/peripherals/usb.rst']
USB_DOCS = ['api-reference/peripherals/usb.rst',
'api-guides/usb-console.rst',
'api-guides/dfu.rst']
ULP_DOCS = ['api-guides/ulp.rst', 'api-guides/ulp_macros.rst']
RISCV_COPROC_DOCS = ['api-guides/ulp-risc-v.rst',]
XTENSA_DOCS = ['api-guides/hlinterrupts.rst']
RISCV_DOCS = ['api-guides/hlinterrupts.rst']
RISCV_DOCS = []
ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
'api-reference/system/himem.rst',
'api-guides/RF_calibration.rst',
'api-guides/romconsole.rst',
'api-reference/system/ipc.rst',
'security/secure-boot-v1.rst',
'api-reference/peripherals/secure_element.rst',
@ -180,15 +185,12 @@ ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-guides/ulps2_instruction_set.rst',
'api-guides/dfu.rst',
'api-guides/usb-console.rst',
'api-guides/ulp-risc-v.rst',
'api-reference/peripherals/hmac.rst',
'api-reference/peripherals/ds.rst',
'api-reference/peripherals/spi_slave_hd.rst',
'api-reference/peripherals/temp_sensor.rst',
'api-reference/system/async_memcpy.rst',
'api-reference/peripherals/usb.rst',
'api-reference/peripherals/dac.rst']
ESP32C3_DOCS = []
@ -205,6 +207,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
'SOC_DAC_PERIPH_NUM':DAC_DOCS,
'SOC_TOUCH_SENSOR_NUM':TOUCH_SENSOR_DOCS,
'SOC_ULP_SUPPORTED':ULP_DOCS,
'SOC_RISCV_COPROC_SUPPORTED':RISCV_COPROC_DOCS,
'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS,
'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS,
'esp32':ESP32_DOCS,
@ -240,7 +243,7 @@ pygments_style = 'sphinx'
project_slug = 'esp-idf'
versions_url = 'https://dl.espressif.com/dl/esp-idf/idf_versions.js'
idf_targets = ['esp32', 'esp32s2']
idf_targets = ['esp32', 'esp32s2', 'esp32c3']
languages = ['en', 'zh_CN']
project_homepage = 'https://github.com/espressif/esp-idf'
@ -451,7 +454,8 @@ def setup_config_values(app, config):
# Sets up global config values needed by other extensions
idf_target_title_dict = {
'esp32': 'ESP32',
'esp32s2': 'ESP32-S2'
'esp32s2': 'ESP32-S2',
'esp32c3': 'ESP32-C3'
}
app.add_config_value('idf_target_title_dict', idf_target_title_dict, 'env')

8
docs/doxygen/Doxyfile_common
View File

@ -100,8 +100,6 @@ INPUT = \
$(IDF_PATH)/components/driver/include/driver/i2c.h \
$(IDF_PATH)/components/driver/include/driver/i2s.h \
$(IDF_PATH)/components/driver/include/driver/ledc.h \
$(IDF_PATH)/components/driver/include/driver/mcpwm.h \
$(IDF_PATH)/components/driver/include/driver/pcnt.h \
$(IDF_PATH)/components/driver/include/driver/rmt.h \
$(IDF_PATH)/components/driver/include/driver/sigmadelta.h \
$(IDF_PATH)/components/driver/include/driver/spi_common.h \
@ -109,7 +107,6 @@ INPUT = \
$(IDF_PATH)/components/driver/include/driver/spi_slave.h \
$(IDF_PATH)/components/driver/include/driver/spi_slave_hd.h \
$(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/adc.h \
$(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \
$(IDF_PATH)/components/driver/include/driver/timer.h \
$(IDF_PATH)/components/driver/include/driver/touch_sensor_common.h \
$(IDF_PATH)/components/driver/include/driver/twai.h \
@ -120,10 +117,8 @@ INPUT = \
$(IDF_PATH)/components/hal/include/hal/dma_types.h \
$(IDF_PATH)/components/hal/include/hal/gpio_types.h \
$(IDF_PATH)/components/hal/include/hal/uart_types.h \
$(IDF_PATH)/components/hal/include/hal/mcpwm_types.h \
$(IDF_PATH)/components/hal/include/hal/rmt_types.h \
$(IDF_PATH)/components/hal/include/hal/spi_types.h \
$(IDF_PATH)/components/hal/include/hal/pcnt_types.h \
$(IDF_PATH)/components/hal/include/hal/i2s_types.h \
$(IDF_PATH)/components/hal/include/hal/rtc_io_types.h \
$(IDF_PATH)/components/hal/include/hal/sigmadelta_types.h \
@ -135,10 +130,7 @@ INPUT = \
$(IDF_PATH)/components/hal/include/hal/twai_types.h \
$(IDF_PATH)/components/hal/include/hal/touch_sensor_types.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/adc_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/dac_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/uart_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/rtc_io_channel.h \
## esp_netif - API Reference
$(IDF_PATH)/components/esp_netif/include/esp_netif.h \
$(IDF_PATH)/components/esp_netif/include/esp_netif_net_stack.h \

8
docs/doxygen/Doxyfile_esp32
View File

@ -1,4 +1,12 @@
INPUT += \
$(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/dac.h \
$(IDF_PATH)/components/esp32/include/esp32/himem.h \
$(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/dac_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/rtc_io_channel.h \
$(IDF_PATH)/components/driver/include/driver/mcpwm.h \
$(IDF_PATH)/components/hal/include/hal/mcpwm_types.h \
$(IDF_PATH)/components/driver/include/driver/pcnt.h \
$(IDF_PATH)/components/hal/include/hal/pcnt_types.h \
$(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h

6
docs/doxygen/Doxyfile_esp32s2
View File

@ -4,4 +4,10 @@ INPUT += \
$(IDF_PATH)/components/esp32s2/include/esp_hmac.h \
$(IDF_PATH)/components/esp32s2/include/esp_ds.h \
$(IDF_PATH)/components/ulp/include/esp32s2/ulp_riscv.h \
$(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/dac_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
$(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/rtc_io_channel.h \
$(IDF_PATH)/components/driver/include/driver/pcnt.h \
$(IDF_PATH)/components/hal/include/hal/pcnt_types.h \
$(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h

10
docs/en/about.rst
View File

@ -6,14 +6,20 @@ About
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.
The {IDF_TARGET_NAME} is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two Xtensa® 32-bit LX6 CPU, 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.
The {IDF_TARGET_NAME} is a 2.4 GHz Wi-Fi module, which integrates a Xtensa® 32-bit LX7 CPU, with up to 600 DMIPS processing power.
.. only:: esp32c3
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 Bluetooth Low Energy combo, which integrates a 32-bit RISC-V RV32IMC single-core processor.
.. figure:: ../_static/about-doc.png
:align: center

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.

6
docs/en/api-reference/system/heap_debug.rst
View File

@ -57,7 +57,7 @@ The example below show how to register a allocation failure callback::
#include "esp_heap_caps.h"
void heap_caps_alloc_failed_hook(size_t requested_size, uint32_t caps, const char *function_name)
void heap_caps_alloc_failed_hook(size_t requested_size, uint32_t caps, const char *function_name)
{
printf("%s was called but failed to allocate %d bytes with 0x%X capabilities. \n",function_name, requested_size, caps);
}
@ -70,7 +70,7 @@ The example below show how to register a allocation failure callback::
void *ptr = heap_caps_malloc(allocation_size, MALLOC_CAP_DEFAULT);
...
}
Finding Heap Corruption
^^^^^^^^^^^^^^^^^^^^^^^
@ -317,7 +317,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-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit </path/to/program/elf>``
4. Run GDB using the following command ``{IDF_TARGET_TOOLCHAIN_PREFIX}-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``

3
docs/en/api-reference/system/power_management.rst
View File

@ -110,7 +110,8 @@ The following drivers will hold the ``ESP_PM_APB_FREQ_MAX`` lock while the drive
- **Ethernet**: between calls to :cpp:func:`esp_eth_driver_install` and :cpp:func:`esp_eth_driver_uninstall`.
- **WiFi**: between calls to :cpp:func:`esp_wifi_start` and :cpp:func:`esp_wifi_stop`. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled.
- **TWAI**: between calls to :cpp:func:`twai_driver_install` and :cpp:func:`twai_driver_uninstall`.
:SOC_BT_SUPPORTED: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` option is set to "External 32kHz crystal".
:SOC_BT_SUPPORTED and esp32: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` option is set to "External 32kHz crystal".
:SOC_BT_SUPPORTED and esp32c3: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held.
The following peripheral drivers are not aware of DFS yet. Applications need to acquire/release locks themselves, when necessary:

3
docs/en/contribute/add-ons-reference.rst
View File

@ -1,5 +1,6 @@
Documentation Add-ons and Extensions Reference
==============================================
:link_to_translation:`zh_CN:[中文]`
This documentation is created using `Sphinx <http://www.sphinx-doc.org/>`_ application that renders text source files in `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_ (``.rst``) format located in :idf:`docs` directory. For some more details on that process, please refer to section :doc:`documenting-code`.
@ -142,7 +143,7 @@ Other Extensions
: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 is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `{\IDF_TARGET_TOOLCHAIN_PREFIX}-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 `{IDF_TARGET_TOOLCHAIN_PREFIX}-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
Also supports markup for defining local (single .rst-file) substitions with the following syntax: {\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"}

9
docs/en/contribute/documenting-code.rst
View File

@ -258,6 +258,7 @@ Chip name:
* esp32
* esp32s2
* esp32c3
Define identifiers from 'sdkconfig.h', generated by the default menuconfig settings for the target, e.g:
@ -345,19 +346,19 @@ When you need to refer to the chip's name, toolchain name, path or other common
For example, the following reStructuredText content:
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 is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `{\IDF_TARGET_TOOLCHAIN_PREFIX}-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC`
Would render in the documentation 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 is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `{IDF_TARGET_TOOLCHAIN_PREFIX}-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
This extension also supports markup for defining local (within a single source file) substitutions. Place a definition like the following into a single line of the RST file:
{\IDF_TARGET_SUFFIX:default="DEFAULT_VALUE", esp32="ESP32_VALUE", esp32s2="ESP32S2_VALUE"}
{\IDF_TARGET_SUFFIX:default="DEFAULT_VALUE", esp32="ESP32_VALUE", esp32s2="ESP32S2_VALUE", esp32c3="ESP32C3_VALUE"}
This will define a target-dependent substitution of the tag {\IDF_TARGET_SUFFIX} in the current RST file. For example:
{\IDF_TARGET_TX_PIN:default="IO3", esp32="IO4", esp32s2="IO5"}
{\IDF_TARGET_TX_PIN:default="IO3", esp32="IO4", esp32s2="IO5", esp32c3="IO6"}
Will define a substitution for the tag {\IDF_TARGET_TX_PIN}, which would be replaced by the text IO5 if sphinx was called with the tag esp32s2.

2
docs/en/get-started-legacy/index.rst
View File

@ -299,7 +299,7 @@ If you run the given command and see errors such as "Failed to connect", there m
In general, you should have no problems with the official esp-idf development boards. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
- Your hardware does not have the DTR and RTS lines connected to ``GPIO0`` and ``CIHP_PU``
- Your hardware does not have the DTR and RTS lines connected to ``GPIO0`` and ``CHIP_PU``
- The DTR and RTS lines are configured differently
- There are no such serial control lines at all

78
docs/en/get-started/index.rst
View File

@ -2,11 +2,11 @@
Get Started
***********
{IDF_TARGET_CORE_NUM:default="2", esp32="2", esp32s2="1"}
{IDF_TARGET_CORE_NUM:default="2", esp32="2", esp32s2="1", esp32c3="1"}
{IDF_TARGET_FEATURES:default="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32s2="WiFi, silicon revision 0, 2MB external flash"}
{IDF_TARGET_FEATURES:default="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32s2="WiFi, silicon revision 0, 2MB external flash", esp32c3="WiFi/BLE, silicon revision 0, 2MB external flash"}
{IDF_TARGET_HEAP_SIZE:default="298968", esp32="298968", esp32s2="253900"}
{IDF_TARGET_HEAP_SIZE:default="298968", esp32="298968", esp32s2="253900", esp32c3="337332"}
:link_to_translation:`zh_CN:[中文]`
@ -28,7 +28,7 @@ Introduction
* Wi-Fi (2.4 GHz band)
* Bluetooth
* Dual high performance cores
* Dual high performance Xtensa® 32-bit LX6 CPU cores
* Ultra Low Power co-processor
* Multiple peripherals
@ -36,12 +36,20 @@ Introduction
.. only:: esp32s2
* Wi-Fi (2.4 GHz band)
* High performance single-core
* High performance single core Xtensa® 32-bit LX7 CPU
* Ultra Low Power co-processor running either RISC-V or FSM core
* Multiple peripherals
* Built-in security hardware
* USB OTG interface
.. only:: esp32c3
* Wi-Fi (2.4 GHz band)
* Bluetooth Low Energy
* High performance 32-bit RISC-V single-core processor
* Multiple peripherals
* Built-in security hardware
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.
@ -99,11 +107,17 @@ If you have one of {IDF_TARGET_NAME} development boards listed below, you can cl
.. toctree::
:maxdepth: 1
ESP32-S2-Saola-1 <../hw-reference/esp32s2/user-guide-saola-1-v1.2>
ESP32-S2-DevKitM-1(U) <../hw-reference/esp32s2/user-guide-devkitm-1-v1>
ESP32-S2-Kaluga-Kit <../hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit>
.. only:: esp32c3
.. note::
No hardware guides for ESP32-C3 published yet.
.. _get-started-step-by-step:
Installation Step by Step
@ -486,21 +500,22 @@ For more information on idf.py arguments, see :ref:`idf.py`.
Encountered Issues While Flashing?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
{IDF_TARGET_STRAP_GPIO:default="GPIO0", esp32="GPIO0", esp32s2="GPIO0", esp32c3="GPIO9"}
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset described below, and if it does not help you can find more details about possible issues in `Troubleshooting <https://github.com/espressif/esptool#bootloader-wont-respond>`_.
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``GPIO0`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
In general, you should have no problems with the official esp-idf development boards. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
- Your hardware does not have the DTR and RTS lines connected to ``GPIO0`` and ``CIHP_PU``
- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``
- The DTR and RTS lines are configured differently
- There are no such serial control lines at all
Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an esp-idf development board, hold down the **Boot** button (``GPIO0``) and press the **EN** button (``CHIP_PU``).
- For other types of hardware, try pulling ``GPIO0`` down.
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an esp-idf development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_GPIO}``) and press the **EN** button (``CHIP_PU``).
- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_GPIO}`` down.
Normal Operation
@ -588,6 +603,47 @@ When flashing, you will see the output log similar to the following:
Hard resetting via RTS pin...
Done
.. only:: esp32c3
.. code-block:: none
...
esptool.py --chip esp32c3 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x0 bootloader/bootloader.bin 0x10000 hello-world.bin
esptool.py v3.0
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C3
Features: Wi-Fi
Crystal is 40MHz
MAC: 7c:df:a1:40:02:a4
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 4238.1 kbit/s)...
Hash of data verified.
Compressed 18960 bytes to 11311...
Writing at 0x00000000... (100 %)
Wrote 18960 bytes (11311 compressed) at 0x00000000 in 0.3 seconds (effective 584.9 kbit/s)...
Hash of data verified.
Compressed 145520 bytes to 71984...
Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 145520 bytes (71984 compressed) at 0x00010000 in 2.3 seconds (effective 504.4 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done
If there are no issues by the end of the flash process, the board will reboot and start up the “hello_world” application.
If you'd like to use the Eclipse or VS Code IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`, :doc:`VS Code guide <vscode-setup>`.
@ -625,7 +681,7 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
To exit IDF monitor use the shortcut ``Ctrl+]``.
.. only:: esp32

14
docs/en/get-started/linux-setup-scratch.rst
View File

@ -68,22 +68,22 @@ Download ``crosstool-NG`` and build it:
Build the toolchain::
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
./ct-ng {IDF_TARGET_TOOLCHAIN_PREFIX}
./ct-ng build
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
chmod -R u+w builds/{IDF_TARGET_TOOLCHAIN_PREFIX}
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``.
Toolchain will be built in ``~/esp/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}``.
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-{IDF_TARGET_TOOLCHAIN_NAME}-elf/``, and copy the build output to this directory.
Choose a directory, for example ``~/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/``, 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-{IDF_TARGET_TOOLCHAIN_NAME}-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 ``{IDF_TARGET_TOOLCHAIN_PREFIX}`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH="$HOME/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:$PATH"
export PATH="$HOME/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/bin:$PATH"
.. note::
@ -96,7 +96,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-{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
/home/user-name/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/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.

6
docs/en/get-started/macos-setup-scratch.rst
View File

@ -73,11 +73,11 @@ Download ``crosstool-NG`` and build it:
Build the toolchain::
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
./ct-ng {IDF_TARGET_TOOLCHAIN_PREFIX}
./ct-ng build
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
chmod -R u+w builds/{IDF_TARGET_TOOLCHAIN_PREFIX}
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.
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}/bin`` to ``PATH`` environment variable.
Python 2 deprecation
====================

6
docs/en/get-started/windows-setup-scratch.rst
View File

@ -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-{IDF_TARGET_TOOLCHAIN_NAME}-elf``.
Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``{IDF_TARGET_TOOLCHAIN_PREFIX}``.
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``.
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\{IDF_TARGET_TOOLCHAIN_PREFIX}\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-{IDF_TARGET_TOOLCHAIN_NAME}-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\{IDF_TARGET_TOOLCHAIN_PREFIX}\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
.. _add-directory-windows-path:

2
docs/en/hw-reference/index.rst
View File

@ -6,7 +6,7 @@
.. toctree::
:maxdepth: 3
Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>
:esp32 or esp32s2: Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>
:esp32: Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
:esp32s2: Datasheet (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf>
:esp32: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>

10
docs/en/index.rst
View File

@ -2,7 +2,7 @@ ESP-IDF Programming Guide
=========================
:link_to_translation:`zh_CN:[中文]`
This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 and ESP32-S Series SoCs <https://www.espressif.com/en/products/hardware/socs>`_.
This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32, ESP32-S and ESP32-C Series SoCs <https://www.espressif.com/en/products/hardware/socs>`_.
.. only:: html
@ -12,6 +12,11 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
This document describes using ESP-IDF with the {IDF_TARGET_NAME} SoC.
.. only:: esp32c3
.. warning::
Not all documents are updated for ESP32-C3 yet.
================== ================== ==================
|Get Started|_ |API Reference|_ |H/W Reference|_
@ -58,8 +63,7 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
Copyrights <COPYRIGHT>
About <about>
语言/Languages <languages>
Guide Downloads <https://readthedocs.com/projects/espressif-esp-idf/downloads/>
* :ref:`genindex`

4
docs/en/resources.rst
View File

@ -17,7 +17,7 @@ Useful Links
* Check the `Issues <https://github.com/espressif/esp-idf/issues>`_ section on GitHub if you find a bug or have a feature request. Please check existing `Issues <https://github.com/espressif/esp-idf/issues>`_ before opening a new one.
* A comprehensive collection of `solutions <https://github.com/espressif/esp-iot-solution#solutions>`_, `practical applications <https://github.com/espressif/esp-iot-solution#esp32-iot-example-list>`_, `components and drivers <https://github.com/espressif/esp-iot-solution#components>`_ based on ESP-IDF is available in `ESP32 IoT Solution <https://github.com/espressif/esp-iot-solution>`_ repository. In most of cases descriptions are provided both in English and in 中文.
* A comprehensive collection of `solutions <https://github.com/espressif/esp-iot-solution#solutions>`_, `practical applications <https://github.com/espressif/esp-iot-solution#esp32-iot-example-list>`_, `components and drivers <https://github.com/espressif/esp-iot-solution#components>`_ based on ESP-IDF is available in `ESP IoT Solution <https://github.com/espressif/esp-iot-solution>`_ repository. In most of cases descriptions are provided both in English and in 中文.
* To develop applications using Arduino platform, refer to `Arduino core for ESP32 WiFi chip <https://github.com/espressif/arduino-esp32#readme>`_.
@ -25,6 +25,6 @@ Useful Links
* If you're interested in contributing to ESP-IDF, please check the :doc:`contribute/index`.
* For additional ESP32 product related information, please refer to `documentation <https://espressif.com/en/support/download/documents>`_ section of `Espressif <https://espressif.com/en/support/download/documents>`__ site.
* For additional {IDF_TARGET_NAME} product related information, please refer to `documentation <https://espressif.com/en/support/download/documents>`_ section of `Espressif <https://espressif.com/en/support/download/documents>`__ site.
* `Download <https://readthedocs.com/projects/espressif-esp-idf/downloads/>`_ latest and previous versions of this documentation in PDF and HTML format.

4
docs/en/security/flash-encryption.rst
View File

@ -282,14 +282,14 @@ To test flash encryption process, take the following steps:
A sample output of the first {IDF_TARGET_NAME} boot after enabling flash encryption is given below:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}_log.inc
.. include:: {IDF_TARGET_PATH_NAME}_log.inc
:start-after: first_boot_enc
:end-before: ------
A sample output of subsequent {IDF_TARGET_NAME} boots just mentions that flash encryption is already enabled:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}_log.inc
.. include:: {IDF_TARGET_PATH_NAME}_log.inc
:start-after: already_en_enc
:end-before: ------

2
docs/idf_extensions/build_system/__init__.py
View File

@ -16,7 +16,7 @@ import sys
project_path = os.path.abspath(os.path.dirname(__file__))
# Targets which needs --preview to build
PREVIEW_TARGETS = ['esp32c3']
PREVIEW_TARGETS = []
def setup(app):

6
docs/idf_extensions/format_idf_target.py
View File

@ -39,8 +39,8 @@ class StringSubstituter:
Supports the following replacements (examples shown is for target=esp32s2):
{IDF_TARGET_NAME}, replaced with the current target name, e.g. ESP32-S2 Beta
{IDF_TARGET_TOOLCHAIN_PREFIX}, replaced with the toolchain prefix, e.g. xtensa-esp32-elf
{IDF_TARGET_PATH_NAME}, replaced with the path name, e.g. esp32s2
{IDF_TARGET_TOOLCHAIN_NAME}, replaced with the toolchain name, e.g. esp32s2
{IDF_TARGET_CFG_PREFIX}, replaced with the prefix used for config parameters, e.g. ESP32S2
{IDF_TARGET_TRM_EN_URL}, replaced with the url to the English technical reference manual
{IDF_TARGET_TRM_CH_URL}, replaced with the url to the Chinese technical reference manual
@ -52,7 +52,7 @@ class StringSubstituter:
"""
TARGET_NAMES = {'esp32': 'ESP32', 'esp32s2': 'ESP32-S2', 'esp32c3': 'ESP32-C3'}
TOOLCHAIN_NAMES = {'esp32': 'esp32', 'esp32s2': 'esp32s2', 'esp32c3': 'esp32c3'}
TOOLCHAIN_PREFIX = {'esp32': 'xtensa-esp32-elf', 'esp32s2': 'xtensa-esp32s2-elf', 'esp32c3': 'riscv32-esp-elf'}
CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2', 'esp32c3': 'ESP32C3'}
TRM_EN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf',
@ -76,7 +76,7 @@ class StringSubstituter:
self.add_pair('{IDF_TARGET_NAME}', self.TARGET_NAMES[config.idf_target])
self.add_pair('{IDF_TARGET_PATH_NAME}', config.idf_target)
self.add_pair('{IDF_TARGET_TOOLCHAIN_NAME}', self.TOOLCHAIN_NAMES[config.idf_target])
self.add_pair('{IDF_TARGET_TOOLCHAIN_PREFIX}', self.TOOLCHAIN_PREFIX[config.idf_target])
self.add_pair('{IDF_TARGET_CFG_PREFIX}', self.CONFIG_PREFIX[config.idf_target])
self.add_pair('{IDF_TARGET_TRM_EN_URL}', self.TRM_EN_URL[config.idf_target])
self.add_pair('{IDF_TARGET_TRM_CN_URL}', self.TRM_CN_URL[config.idf_target])

2
docs/sphinx-known-warnings.txt
View File

@ -77,3 +77,5 @@ wear-levelling.rst:line: WARNING: Duplicate declaration, bool esp_vfs_fat_mount_
wear-levelling.rst:line: WARNING: Duplicate declaration, int esp_vfs_fat_mount_config_t::max_files
wear-levelling.rst:line: WARNING: Duplicate declaration, size_t esp_vfs_fat_mount_config_t::allocation_unit_size
wear-levelling.rst:line: WARNING: Duplicate declaration, esp_vfs_fat_mount_config_t
bootloader.rst:line: WARNING: undefined label: config_secure_boot (if the link has no caption the label must precede a section header)
secure-boot-v2.rst:line: WARNING: undefined label: config_secure_boot_insecure (if the link has no caption the label must precede a section header)

4
docs/test/test_sphinx_idf_extensions.py
View File

@ -30,7 +30,7 @@ class TestFormatIdfTarget(unittest.TestCase):
self.assertEqual(self.str_sub.substitute_strings['{IDF_TARGET_NAME}'], 'ESP32')
self.assertEqual(self.str_sub.substitute_strings['{IDF_TARGET_PATH_NAME}'], 'esp32')
self.assertEqual(self.str_sub.substitute_strings['{IDF_TARGET_TOOLCHAIN_NAME}'], 'esp32')
self.assertEqual(self.str_sub.substitute_strings['{IDF_TARGET_TOOLCHAIN_PREFIX}'], 'xtensa-esp32-elf')
self.assertEqual(self.str_sub.substitute_strings['{IDF_TARGET_CFG_PREFIX}'], 'ESP32')
self.assertEqual(self.str_sub.substitute_strings['{IDF_TARGET_TRM_EN_URL}'],
'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf')
@ -39,7 +39,7 @@ class TestFormatIdfTarget(unittest.TestCase):
def test_sub(self):
content = ('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. '
'{IDF_TARGET_TOOLCHAIN_PREFIX}-gcc with CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC. '
'TRM can be found at {IDF_TARGET_TRM_EN_URL} or {IDF_TARGET_TRM_CN_URL}')
expected = ('This is a ESP32, with esp32/soc.c, compiled with xtensa-esp32-elf-gcc with CONFIG_ESP32_MULTI_DOC. '

2
docs/zh_CN/api-guides/fatal-errors.rst
View File

@ -169,7 +169,7 @@ GDB Stub
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/>.

6
docs/zh_CN/api-guides/index.rst
View File

@ -15,7 +15,7 @@ API 指南
错误处理 <error-handling>
:SOC_BT_SUPPORTED: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
核心转储 <core_dump>
核心转储 <core_dump>
事件处理 <event-handling>
:SOC_SPIRAM_SUPPORTED: 片外 SPI RAM <external-ram>
严重错误 <fatal-errors>
@ -25,11 +25,11 @@ API 指南
硬件抽象层 <hardware-abstraction>
:CONFIG_IDF_TARGET_ARCH_XTENSA: 高层中断 <hlinterrupts>
JTAG 调试 <jtag-debugging/index>
链接脚本生成机制 <linker-script-generation>
链接脚本生成机制 <linker-script-generation>
lwIP TCP/IP 协议栈 <lwip>
分区表 <partition-tables>
:esp32: 射频校准 <RF_calibration>
ROM 调试控制台 <romconsole>
:esp32: ROM 调试控制台 <romconsole>
:esp32: 安全启动 <../security/secure-boot-v1>
安全启动 V2 <../security/secure-boot-v2>
线程本地存储 <thread-local-storage>

8
docs/zh_CN/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 @@
配置硬件
^^^^^^^^
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: devkit-hw-config
:end-before: ---
* 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: jtag-pins
:end-before: ---
@ -118,7 +118,7 @@ MacOS
4. 运行 OpenOCD::
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd
:end-before: ---

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

@ -10,7 +10,7 @@
1. 找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的引脚/信号。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: jtag-pins
:end-before: ---

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

@ -24,7 +24,7 @@ JTAG 调试
介绍使用 OpenOCD 和 GDB 通过 JTAG 接口调试 {IDF_TARGET_NAME} 时的注意事项和补充内容。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: devkit-defs
:end-before: ---
@ -52,7 +52,7 @@ JTAG 调试
工作原理
--------
通过 JTAG（Joint Test Action Group）接口使用 OpenOCD 调试 {IDF_TARGET_NAME} 时所需要的一些关键的软件和硬件包括 **xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb
通过 JTAG（Joint Test Action Group）接口使用 OpenOCD 调试 {IDF_TARGET_NAME} 时所需要的一些关键的软件和硬件包括 **{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb
调试器**，**OpenOCD 片上调试器** 和连接到 **{IDF_TARGET_NAME}** 目标的 **JTAG 适配器**。
.. figure:: ../../../_static/jtag-debugging-overview_zh.jpg
@ -148,7 +148,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
打开终端，按照快速入门中的指南 :ref:`设置好开发环境 <get-started-set-up-env>` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd
:end-before: ---
@ -160,7 +160,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
现在应该可以看到如下输入（此日志来自 |run-openocd-device-name|）:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-output
:end-before: ---
@ -178,7 +178,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-upload
:end-before: ---
@ -200,7 +200,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
启动调试器
----------
{IDF_TARGET_NAME} 的工具链中带有 GNU 调试器（简称 GDB） ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb``，它和其它工具链软件存放在同一个 bin 目录下。除了直接在命令行终端中调用并操作 GDB 外，还可以在 IDE (例如 Eclipse，Visual Studio Code 等）中调用它，在图形用户界面的帮助下间接操作 GDB，无需在终端中输入任何命令。
{IDF_TARGET_NAME} 的工具链中带有 GNU 调试器（简称 GDB） ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb``，它和其它工具链软件存放在同一个 bin 目录下。除了直接在命令行终端中调用并操作 GDB 外，还可以在 IDE (例如 Eclipse，Visual Studio Code 等）中调用它，在图形用户界面的帮助下间接操作 GDB，无需在终端中输入任何命令。
关于以上两种调试器的使用方法，详见以下链接。
@ -265,13 +265,13 @@ Windows 用户可以执行:
运行本地编译的 OpenOCD 的示例如下（Linux 和 macOS 用户）:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-src-linux
:end-before: ---
Windows 用户:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-src-win
:end-before: ---

16
docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst
View File

@ -37,7 +37,7 @@
.. 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 @@ OpenOCD 有很多种配置文件（``*.cfg``），它们位于 OpenOCD 安装目
{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 @@ TCL 语言中为变量赋值的语法是:
* - ``ESP_SEMIHOST_BASEDIR``
- 设置 semihosting 在主机端的默认目录。
.. 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 @@ TCL 语言中为变量赋值的语法是:
如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 引脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下引脚：
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: jtag-pins
:end-before: ---
@ -263,19 +263,19 @@ Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认
OpenOCD 端：
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-d3
:end-before: ---
这种方式会将日志输出到文件，但是它会阻止调试信息打印在终端上。当有大量信息需要输出的时候（比如调试等级提高到 ``-d3``）这是个不错的选择。如果你仍然希望在屏幕上看到调试日志，请改用以下命令：
.. 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: ---
@ -285,4 +285,4 @@ Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认
4. 请将 ``openocd_log.txt`` 和 ``gdb_log.txt`` 文件附在你的问题报告中。
.. _OpenOCD 参考手册: http://openocd.org/doc/html/index.html
.. _OpenOCD 参考手册: http://openocd.org/doc/html/index.html

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

@ -35,7 +35,7 @@
GDB 硬件调试的配置 - Main 选项卡
6. 点击 “Debugger” 选项卡，在 “GDB Command” 栏中输入 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb`` 来调用调试器。
6. 点击 “Debugger” 选项卡，在 “GDB Command” 栏中输入 ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb`` 来调用调试器。
7. 更改 “Remote host” 的默认配置，在 “Port number” 下面输入 ``3333``。
@ -134,7 +134,7 @@
::
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -x gdbinit build/blink.elf
.. highlight:: none
@ -142,14 +142,14 @@
::
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/>.
@ -158,7 +158,7 @@
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/{IDF_TARGET_TOOLCHAIN_NAME}/./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: {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)
@ -202,7 +202,7 @@
在终端中运行 OpenOCD，其配置信息来源于环境变量或者命令行。默认会使用 ``OPENOCD_SCRIPTS`` 环境变量中指定的脚本路径，它是由 ESP-IDF 项目仓库中的导出脚本（``export.sh`` or ``export.bat``）添加到系统环境变量中的。
当然，我们可以在命令行中通过 ``--openocd-scripts`` 来覆盖这个变量的值。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: idf-py-openocd-default-cfg
:end-before: ---

4
docs/zh_CN/api-guides/tools/idf-monitor.rst
View File

@ -109,7 +109,7 @@ IDF 监视器为寄存器转储补充如下信息::
IDF 监视器在后台运行以下命令，解码各地址::
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 +128,7 @@ IDF 监视器在后台运行以下命令，解码各地址::
IDF 监控器在后台运行如下命令::
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
输出筛选

4
docs/zh_CN/api-guides/ulp.rst
View File

@ -31,7 +31,7 @@ ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp
1. 用汇编语言编写的 ULP 代码必须导入到一个或多个 `.S` 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。
.. note: 在（通过 ``idf_component_register``）注册组件时，不应将该目录添加到 ``SRC_DIRS`` 参数中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``SRC_DIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别最简单的方式就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也 **不应该** 添加到 ``SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。
.. note: 在注册组件（通过 ``idf_component_register``）时，不应将该目录添加到 ``SRC_DIRS`` 参数中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``SRC_DIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``{IDF_TARGET_TOOLCHAIN_PREFIX}-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别最简单的方式就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也 **不应该** 添加到 ``SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。
2. 注册后从组件 CMakeLists.txt 中调用 ``ulp_embed_binary`` 示例如下::
@ -176,5 +176,5 @@ ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp
如果想禁用定时器（有效防止 ULP 程序再次运行），可在 ULP 代码或主程序中清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位。
.. _binutils-esp32ulp 工具链: https://github.com/espressif/binutils-esp32ulp

2
docs/zh_CN/api-reference/index.rst
View File

@ -6,7 +6,7 @@ API 参考
.. toctree::
:maxdepth: 2
:esp32: Bluetooth <bluetooth/index>
:SOC_BT_SUPPORTED: Bluetooth <bluetooth/index>
Networking <network/index>
Peripherals <peripherals/index>
协议 <protocols/index>

4
docs/zh_CN/contribute/add-ons-reference.rst
View File

@ -144,11 +144,11 @@ CMake 项目模型运行完成后，系统将在构建初期发出 ``idf-info``
:idf_file:`docs/idf_extensions/format_idf_target.py`
通过将 idf_target 发送至 Sphinx 命令行替换 target 相关名称的扩展功能。例如：
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 is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `{\IDF_TARGET_TOOLCHAIN_PREFIX}-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC`
删掉退格键后，将被渲染为
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 is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `{IDF_TARGET_TOOLCHAIN_PREFIX}-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
同时，也支持使用以下语法标记本地（单个 rst 文件）替代文件的定义：
{\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"}

6
docs/zh_CN/contribute/documenting-code.rst
View File

@ -351,11 +351,11 @@ CI build 脚本中添加了检查功能，查找 RST 文件中的硬编码链接
例如，以下 reStructuredText 内容：
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 is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `{\IDF_TARGET_TOOLCHAIN_PREFIX}-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC`
将在文档中渲染为：
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 is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `{IDF_TARGET_TOOLCHAIN_PREFIX}-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
这一扩展也支持定义本地（在单个源文件中）替代名称的标记。请在 RST 文件的一行中插入下示定义语言：
@ -521,7 +521,7 @@ Doxygen 的安装取决于操作系统：
请注意，这一功能仅用于文档写作过程中的检查和测试。其生成的 HTML 页面并非渲染完成后的格式，比如，运行这一指令并不会生成一个列有所有文档的索引，而且如果其中涉及到任何还未生成的文档参考都将导致错误警报出现。
生成 PDF
生成 PDF
""""""""""""
可以使用 ``build_docs.py`` 生成文档的 latex 和 PDF 格式，需安装以下 latex 工具包：

20
docs/zh_CN/get-started/linux-setup-scratch.rst
View File

@ -65,28 +65,28 @@
.. include-build-file:: inc/scratch-build-code.inc
.. 注解:: 在设置支持 64 位 time_t 的工具链时，您需要将 ``crosstool-NG/samples/xtensa-esp32-elf/crosstool.config`` 文件中第 33 和 43 行的可选参数 ``--enable-newlib-long-time_t`` 删除。
.. 注解:: 在设置支持 64 位 time_t 的工具链时，您需要将 ``crosstool-NG/samples/xtensa-esp32-elf/crosstool.config`` 文件中第 33 和 43 行的可选参数 ``--enable-newlib-long-time_t`` 删除。
编译工具链::
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
./ct-ng {IDF_TARGET_TOOLCHAIN_PREFIX}
./ct-ng build
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
chmod -R u+w builds/{IDF_TARGET_TOOLCHAIN_PREFIX}
编译得到的工具链会被保存至 ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``。
编译得到的工具链会被保存至 ``~/esp/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}``。
添加工具链到 PATH 环境变量
===========================
需要将自定义工具链复制到一个二进制目录中，并将其添加到 ``PATH`` 中。例如，您可以将编译好的工具链复制到 ``~/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/`` 目录中。
需要将自定义工具链复制到一个二进制目录中，并将其添加到 ``PATH`` 中。例如，您可以将编译好的工具链复制到 ``~/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/`` 目录中。
为了正常使用工具链，您需要更新 ``~/.profile`` 文件中 ``PATH`` 环境变量。此外，您还可以在 ``~/.profile`` 文件中增加以下代码。这样，所有终端窗口均可以使用 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``::
为了正常使用工具链，您需要更新 ``~/.profile`` 文件中 ``PATH`` 环境变量。此外，您还可以在 ``~/.profile`` 文件中增加以下代码。这样，所有终端窗口均可以使用 ``{IDF_TARGET_TOOLCHAIN_PREFIX}``::
export PATH="$HOME/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:$PATH"
export PATH="$HOME/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/bin:$PATH"
.. 注解::
如果您已将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile`` 两个文件，则请更新 ``.bash_profile``。在 CentOS 环境下, ``alias`` 需要添加到 ``.bashrc`` 文件中。
退出并重新登录以使 ``.profile`` 的更改生效。运行以下命令来检查 ``PATH`` 设置是否正确::
@ -96,12 +96,12 @@
此时您需要检查输出结果的开头中是否包含类似如下的工具链路径::
$ printenv PATH
/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
/home/user-name/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/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`` 应该替换成您安装的主路径。
停用 Python 2
停用 Python 2
====================
Python 2 已经 `结束生命周期 <https://www.python.org/doc/sunset-python-2/>`_，ESP-IDF 很快将不再支持 Python 2。请安装 Python 3.6 或以上版本。可参考上面列出的目前主流 Linux 发行版的安装说明。

8
docs/zh_CN/get-started/macos-setup-scratch.rst
View File

@ -73,14 +73,14 @@ MacPorts 需要完整的 XCode 软件，而 Homebrew 只需要安装 XCode 命
编译工具链::
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
./ct-ng {IDF_TARGET_TOOLCHAIN_PREFIX}
./ct-ng build
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
chmod -R u+w builds/{IDF_TARGET_TOOLCHAIN_PREFIX}
编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` 添加至 ``PATH`` 环境变量。
编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}/bin`` 添加至 ``PATH`` 环境变量。
停用 Python 2
停用 Python 2
====================
Python 2 已经 `结束生命周期 <https://www.python.org/doc/sunset-python-2/>`_，ESP-IDF 很快将不再支持 Python 2。请安装 Python 3.6 或以上版本。可参考上面列出的 macOS 安装说明。

6
docs/zh_CN/get-started/windows-setup-scratch.rst
View File

@ -82,12 +82,12 @@ Python 安装完成后，从 Windows 开始菜单中打开“命令提示符”
|download_link_win32|
将压缩包文件解压到 ``C:\Program Files``（或其他位置）。压缩包文件包含一个 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`` 目录。
将压缩包文件解压到 ``C:\Program Files``（或其他位置）。压缩包文件包含一个 ``{IDF_TARGET_TOOLCHAIN_PREFIX}`` 目录。
然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到 Path 环境变量 <add-directory-windows-path>`。例如，将目录 ``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` 添加到 Path 环境变量。
然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到 Path 环境变量 <add-directory-windows-path>`。例如，将目录 ``C:\Program Files\{IDF_TARGET_TOOLCHAIN_PREFIX}\bin`` 添加到 Path 环境变量。
.. 注解::
如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` 到 Path 环境变量，因为 MSYS2 环境已包含工具链。
如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\{IDF_TARGET_TOOLCHAIN_PREFIX}\bin`` 到 Path 环境变量，因为 MSYS2 环境已包含工具链。
.. _add-directory-windows-path:

2
docs/zh_CN/hw-reference/index.rst
View File

@ -6,7 +6,7 @@
.. toctree::
:maxdepth: 3
{IDF_TARGET_NAME} 技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}>
:esp32 or esp32s2: {IDF_TARGET_NAME} 技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}>
:esp32: ESP32 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>
:esp32s2: ESP32-S2 技术规格书 (PDF) <https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_cn.pdf>
:esp32: ESP32 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_cn.pdf>

2
tools/ci/config/build.yml
View File

@ -291,7 +291,7 @@ build_component_ut_esp32c3:
parallel:
matrix:
- DOCLANG: [ "en", "zh_CN" ]
DOCTGT: [ "esp32", "esp32s2" ]
DOCTGT: [ "esp32", "esp32s2", "esp32c3"]
build_docs_html:
extends: