docs: updated system api-reference chapters for C3

components/esp_timer/Kconfig

@@ -63,7 +63,7 @@ menu "High resolution timer (esp_timer)"
             - "LAC timer of Timer Group 0" implementation is simpler, and has smaller
               run time overhead because software handling of timer overflow is not needed.
 
-            - "SYSTIMER" implementation is similar to "LAC timer of Timer Group 0" but for ESP32-S2 chip.
+            - "SYSTIMER" implementation is similar to "LAC timer of Timer Group 0" but for non ESP32 chips.
 
         config ESP_TIMER_IMPL_FRC2
             bool "FRC2 (legacy) timer"

components/soc/esp32c3/include/soc/soc_caps.h

@@ -5,12 +5,13 @@
 
 #pragma once
 
-#define SOC_CPU_CORES_NUM       1
-#define SOC_GDMA_SUPPORTED      1
-#define SOC_TWAI_SUPPORTED      1
-#define SOC_BT_SUPPORTED        1
-#define SOC_DIG_SIGN_SUPPORTED  1
-#define SOC_HMAC_SUPPORTED      1
+#define SOC_CPU_CORES_NUM           1
+#define SOC_GDMA_SUPPORTED          1
+#define SOC_TWAI_SUPPORTED          1
+#define SOC_BT_SUPPORTED            1
+#define SOC_DIG_SIGN_SUPPORTED      1
+#define SOC_HMAC_SUPPORTED          1
+#define SOC_ASYNC_MEMCPY_SUPPORTED  1
 
 /*-------------------------- DAC CAPS ----------------------------------------*/
 #define SOC_DAC_PERIPH_NUM      0

components/soc/esp32s2/include/soc/soc_caps.h

@@ -50,6 +50,7 @@
 #define SOC_CCOMP_TIMER_SUPPORTED       1
 #define SOC_DIG_SIGN_SUPPORTED          1
 #define SOC_HMAC_SUPPORTED              1
+#define SOC_ASYNC_MEMCPY_SUPPORTED      1
 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3
 
 #define SOC_CACHE_SUPPORT_WRAP          1

components/soc/esp32s3/include/soc/soc_caps.h

@@ -17,6 +17,7 @@
 #define SOC_CCOMP_TIMER_SUPPORTED       1
 #define SOC_DIG_SIGN_SUPPORTED          1
 #define SOC_HMAC_SUPPORTED              1
+#define SOC_ASYNC_MEMCPY_SUPPORTED      1
 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3
 
 

docs/conf_common.py

@@ -169,7 +169,8 @@ 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']
+XTENSA_DOCS = ['api-guides/hlinterrupts.rst',
+               'api-reference/system/perfmon.rst']
 
 RISCV_DOCS = []
 
@@ -211,6 +212,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
                             'SOC_RISCV_COPROC_SUPPORTED':RISCV_COPROC_DOCS,
                             'SOC_DIG_SIGN_SUPPORTED':['api-reference/peripherals/ds.rst'],
                             'SOC_HMAC_SUPPORTED':['api-reference/peripherals/hmac.rst'],
+                            'SOC_ASYNC_MEMCPY_SUPPORTED':['api-reference/system/async_memcpy.rst'],
                             'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS,
                             'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS,
                             'esp32':ESP32_DOCS,

docs/en/api-reference/system/app_image_format.rst

@@ -62,7 +62,7 @@ You can also see the information on segments in the IDF logs while your applicat
 
     For more details on the type of memory segments and their address ranges, see *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Embedded Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__].
 
-.. only:: esp32s2
+.. only:: esp32s2 or esp32c3
 
     For more details on the type of memory segments and their address ranges, see *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Internal Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__].
 

docs/en/api-reference/system/console.rst

@@ -21,7 +21,7 @@ Line editing feature lets users compose commands by typing them, erasing symbols
 
 .. note::
 
-  This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running :example:`system/console` example instead of a command prompt (e.g. ``esp> ``), it means that the serial monitor does not support escape sequences. Programs which are known to work are  GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
+  This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running :example:`system/console` example instead of a command prompt (e.g. ``esp>`` ), it means that the serial monitor does not support escape sequences. Programs which are known to work are  GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
 
 Here is an overview of functions provided by `linenoise`_ library.
 

docs/en/api-reference/system/esp_https_ota.rst

@@ -42,12 +42,10 @@ can be set to lower value which is not possible without enabling this configurat
 Default value of mbedTLS Rx buffer size is set to 16K. By using partial_http_download with max_http_request_size of 4K,
 size of mbedTLS Rx buffer can be reduced to 4K. With this confiuration, memory saving of around 12K is expected.
 
-.. only:: esp32
+Signature Verification
+----------------------
 
-    Signature Verification
-    ----------------------
-
-    For additional security, signature of OTA firmware images can be verified. For that, refer :ref:`secure-ota-updates`
+For additional security, signature of OTA firmware images can be verified. For that, refer :ref:`secure-ota-updates`
 
 API Reference
 -------------

docs/en/api-reference/system/esp_pthread.rst

@@ -5,6 +5,7 @@ Overview
 --------
 
 This module offers Espressif specific extensions to the pthread library that can be used to influence the behaviour of pthreads. Currently the following configuration can be tuned:
+
   * Stack size of the pthreads
   * Priority of the created pthreads
   * Inheriting this configuration across threads

docs/en/api-reference/system/esp_timer.rst

@@ -15,13 +15,17 @@ An interrupt level of the handler depends on the :ref:`CONFIG_ESP_TIMER_INTERRUP
 
 ``esp_timer`` set of APIs provides one-shot and periodic timers, microsecond time resolution, and 64-bit range.
 
-Internally, ``esp_timer`` uses a 64-bit hardware timer :ref:`CONFIG_ESP_TIMER_IMPL`:
+Internally, ``esp_timer`` uses a 64-bit hardware timer, where the implemention depends on :ref:`CONFIG_ESP_TIMER_IMPL`. Available options are:
 
-- LAC timer (ESP32)
-- (legacy) FRC2 timer (ESP32)
-- SYSTIMER for (ESP32-S2)
+.. list::
 
-.. note: The FRC2 is a legacy option for ESP32 until v4.2, a 32-bit hardware timer was used. Starting at v4.2, use the new LAC timer option instead, it has a simpler implementation, and has smaller run time overhead because software handling of timer overflow is not needed.
+    :esp32: - LAC timer
+    :esp32: - (legacy) FRC2 timer
+    :not esp32: - SYSTIMER
+
+.. only:: esp32
+
+    .. note:: The FRC2 is a legacy option for ESP32 until v4.2, a 32-bit hardware timer was used. Starting at v4.2, use the new LAC timer option instead, it has a simpler implementation, and has smaller run time overhead because software handling of timer overflow is not needed.
 
 Timer callbacks can dispatched by two methods:
 
@@ -59,7 +63,7 @@ Callback functions
 
 .. note: Keep the callback functions as short as possible otherwise it will affect all timers.
 
-Timer callbacks which are processed by ``ESP_TIMER_ISR`` method should not have inside the context switch call - ``portYIELD_FROM_ISR()`` instead of this use the :cpp:func:`esp_timer_isr_dispatch_need_yield` function.
+Timer callbacks which are processed by ``ESP_TIMER_ISR`` method should not call the context switch call - ``portYIELD_FROM_ISR()``, instead of this you should use the :cpp:func:`esp_timer_isr_dispatch_need_yield` function.
 The context switch will be done after all ISR dispatch timers have been processed, if required by the system.
 
 esp_timer during the light sleep

docs/en/api-reference/system/heap_debug.rst

@@ -304,13 +304,13 @@ To gather and analyse heap trace do the following on the host:
 
     tb heap_trace_start
     commands
-    mon esp32 sysview start file:///tmp/heap.svdat
+    mon esp sysview start file:///tmp/heap.svdat
     c
     end
 
     tb heap_trace_stop
     commands
-    mon esp32 sysview stop
+    mon esp sysview stop
     end
 
     c

docs/en/api-reference/system/index.rst

@@ -6,7 +6,7 @@ System API
 
     App image format <app_image_format>
     Application Level Tracing <app_trace>
-    :esp32s2: Async Memory Copy <async_memcpy>
+    :SOC_ASYNC_MEMCPY_SUPPORTED: Async Memory Copy <async_memcpy>
     Console Component <console>
     eFuse Manager <efuse>
     Error Codes and Helper Functions <esp_err>
@@ -19,13 +19,13 @@ System API
     Heap Memory Debugging <heap_debug>
     High Resolution Timer <esp_timer>
     :esp32: Himem (large external SPI RAM) API <himem>
-    :esp32: Inter-Processor Call <ipc>
+    :not CONFIG_FREERTOS_UNICORE: Inter-Processor Call <ipc>
     Call function with external stack <esp_function_with_shared_stack>
     Interrupt Allocation <intr_alloc>
     Logging <log>
     Miscellaneous System APIs <system>
     Over The Air Updates (OTA) <ota>
-    Performance Monitor <perfmon>
+    :CONFIG_IDF_TARGET_ARCH_XTENSA: Performance Monitor <perfmon>
     Power Management <power_management>
     Sleep Modes <sleep_modes>
     Watchdogs <wdts>

docs/en/api-reference/system/intr_alloc.rst

@@ -6,17 +6,19 @@ Overview
 
 .. only:: esp32
 
-  The {IDF_TARGET_NAME} has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
-  to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
-  multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
+  The {IDF_TARGET_NAME} has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected to the interrupt mux.
 
 .. only:: esp32s2
 
-  The {IDF_TARGET_NAME} has one core, with 32 interrupts. Each interrupt has a certain priority level, most (but not all) interrupts are connected
-  to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
-  multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
+  The {IDF_TARGET_NAME} has one core, with 32 interrupts. Each interrupt has a certain priority level, most (but not all) interrupts are connected to the interrupt mux.
 
-A driver can allocate an interrupt for a certain peripheral by calling esp_intr_alloc (or esp_intr_alloc_sintrstatus). It can use
+.. only:: esp32c3
+
+  The {IDF_TARGET_NAME} has one core, with 31 interrupts. Each interrupt has a programmable priority level.
+
+Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in multiple drivers. The :cpp:func:`esp_intr_alloc` abstraction exists to hide all these implementation details.
+
+A driver can allocate an interrupt for a certain peripheral by calling :cpp:func:`esp_intr_alloc` (or :cpp:func:`esp_intr_alloc_intrstatus`). It can use
 the flags passed to this function to set the type of interrupt allocated, specifying a specific level or trigger method. The
 interrupt allocation code will then find an applicable interrupt, use the interrupt mux to hook it up to the peripheral, and
 install the given interrupt handler and ISR to it.
@@ -37,48 +39,50 @@ interrupt for DevA is still pending, but because the int line never went low (De
 even when the int for DevB was cleared) the interrupt is never serviced.)
 
 
-Multicore issues
-----------------
+.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
 
-Peripherals that can generate interrupts can be divided in two types:
+  Multicore issues
+  ----------------
 
-  - External peripherals, within the {IDF_TARGET_NAME} but outside the Xtensa cores themselves. Most {IDF_TARGET_NAME} peripherals are of this type.
-  - Internal peripherals, part of the Xtensa CPU cores themselves.
+  Peripherals that can generate interrupts can be divided in two types:
 
-Interrupt handling differs slightly between these two types of peripherals.
+    - External peripherals, within the {IDF_TARGET_NAME} but outside the Xtensa cores themselves. Most {IDF_TARGET_NAME} peripherals are of this type.
+    - Internal peripherals, part of the Xtensa CPU cores themselves.
 
-Internal peripheral interrupts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  Interrupt handling differs slightly between these two types of peripherals.
 
-Each Xtensa CPU core has its own set of six internal peripherals:
+  Internal peripheral interrupts
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  - Three timer comparators
-  - A performance monitor
-  - Two software interrupts.
+  Each Xtensa CPU core has its own set of six internal peripherals:
 
-Internal interrupt sources are defined in esp_intr_alloc.h as ``ETS_INTERNAL_*_INTR_SOURCE``.
+    - Three timer comparators
+    - A performance monitor
+    - Two software interrupts.
 
-These peripherals can only be configured from the core they are associated with. When generating an interrupt,
-the interrupt they generate is hard-wired to their associated core; it's not possible to have e.g. an internal
-timer comparator of one core generate an interrupt on another core. That is why these sources can only be managed
-using a task running on that specific core. Internal interrupt sources are still allocatable using esp_intr_alloc
-as normal, but they cannot be shared and will always have a fixed interrupt level (namely, the one associated in
-hardware with the peripheral).
+  Internal interrupt sources are defined in esp_intr_alloc.h as ``ETS_INTERNAL_*_INTR_SOURCE``.
 
-External Peripheral Interrupts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  These peripherals can only be configured from the core they are associated with. When generating an interrupt,
+  the interrupt they generate is hard-wired to their associated core; it's not possible to have e.g. an internal
+  timer comparator of one core generate an interrupt on another core. That is why these sources can only be managed
+  using a task running on that specific core. Internal interrupt sources are still allocatable using esp_intr_alloc
+  as normal, but they cannot be shared and will always have a fixed interrupt level (namely, the one associated in
+  hardware with the peripheral).
 
-The remaining interrupt sources are from external peripherals. These are defined in soc/soc.h as ``ETS_*_INTR_SOURCE``.
+  External Peripheral Interrupts
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Non-internal interrupt slots in both CPU cores are wired to an interrupt multiplexer, which can be used to
-route any external interrupt source to any of these interrupt slots.
+  The remaining interrupt sources are from external peripherals. These are defined in soc/soc.h as ``ETS_*_INTR_SOURCE``.
 
-- Allocating an external interrupt will always allocate it on the core that does the allocation.
-- Freeing an external interrupt must always happen on the same core it was allocated on.
-- Disabling and enabling external interrupts from another core is allowed.
-- Multiple external interrupt sources can share an interrupt slot by passing ``ESP_INTR_FLAG_SHARED`` as a flag to esp_intr_alloc().
+  Non-internal interrupt slots in both CPU cores are wired to an interrupt multiplexer, which can be used to
+  route any external interrupt source to any of these interrupt slots.
 
-Care should be taken when calling esp_intr_alloc() from a task which is not pinned to a core. During task switching, these tasks can migrate between cores. Therefore it is impossible to tell which CPU the interrupt is allocated on, which makes it difficult to free the interrupt handle and may also cause debugging difficulties. It is advised to use xTaskCreatePinnedToCore() with a specific CoreID argument to create tasks that will allocate interrupts. In the case of internal interrupt sources, this is required.
+  - Allocating an external interrupt will always allocate it on the core that does the allocation.
+  - Freeing an external interrupt must always happen on the same core it was allocated on.
+  - Disabling and enabling external interrupts from another core is allowed.
+  - Multiple external interrupt sources can share an interrupt slot by passing ``ESP_INTR_FLAG_SHARED`` as a flag to esp_intr_alloc().
+
+  Care should be taken when calling esp_intr_alloc() from a task which is not pinned to a core. During task switching, these tasks can migrate between cores. Therefore it is impossible to tell which CPU the interrupt is allocated on, which makes it difficult to free the interrupt handle and may also cause debugging difficulties. It is advised to use xTaskCreatePinnedToCore() with a specific CoreID argument to create tasks that will allocate interrupts. In the case of internal interrupt sources, this is required.
 
 IRAM-Safe Interrupt Handlers
 ----------------------------

docs/en/api-reference/system/ipc.rst

@@ -4,7 +4,7 @@ Inter-Processor Call
 Overview
 --------
 
-Due to the dual core nature of the ESP32, there are instances where a certain
+Due to the dual core nature of the {IDF_TARGET_NAME}, there are instances where a certain
 function must be run in the context of a particular core (e.g. allocating
 ISR to an interrupt source of a particular core). The IPC (Inter-Processor
 Call) feature allows for the execution of functions on a particular CPU.

docs/en/api-reference/system/mem_alloc.rst

@@ -45,7 +45,9 @@ At startup, the DRAM heap contains all data memory which is not statically alloc
 
 To find the amount of statically allocated memory, use the :ref:`idf.py size <idf.py-size>` command.
 
-.. note:: Due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap.
+.. only:: esp32
+
+    .. note:: Due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap.
 
 .. note:: At runtime, the available heap DRAM may be less than calculated at compile time, because at startup some memory is allocated from the heap before the FreeRTOS scheduler is started (including memory for the stacks of initial FreeRTOS tasks).
 

docs/en/api-reference/system/ota.rst

@@ -195,14 +195,17 @@ Restrictions:
 
   - In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app.
 
+
+.. _secure-ota-updates:
+
+Secure OTA Updates Without Secure boot
+--------------------------------------
+
+The verification of signed OTA updates can be performed even without enabling hardware secure boot. This can be achieved by setting :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT` and :ref:`CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT`
+
 .. only:: esp32
 
-  .. _secure-ota-updates:
-
-  Secure OTA Updates Without Secure boot
-  --------------------------------------
-
-  The verification of signed OTA updates can be performed even without enabling hardware secure boot. For doing so, refer :ref:`signed-app-verify`
+  For more information refer to :ref:`signed-app-verify`
 
 
 OTA Tool (otatool.py)

docs/en/api-reference/system/system.rst

@@ -39,7 +39,7 @@ These APIs allow querying and customizing MAC addresses for different network in
 
 In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from internal eFuse, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details.
 
-.. only:: esp32
+.. only:: esp32 and esp32c3
 
     +---------------+--------------------------------+----------------------------------+
     | Interface     | MAC address                    | MAC address                      |
@@ -106,9 +106,9 @@ If the universally administered MAC addresses are not enough for all of the netw
 
 See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_ for the definition of local and universally administered MAC addresses.
 
-.. only:: esp32
+.. only:: esp32 and esp32c3
 
-    The number of universally administered MAC address can be configured using :ref:`CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES`.
+    The number of universally administered MAC address can be configured using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES`.
 
     If the number of universal MAC addresses is two, only two interfaces (Wi-Fi Station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (Wi-Fi SoftAP and Ethernet) receive local MAC addresses. These are derived from the universal Wi-Fi station and Bluetooth MAC addresses, respectively.
 
@@ -116,9 +116,15 @@ See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local
 
     When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)
 
-.. todo::
+.. only:: esp32s2
 
-   Add illustration for ESP32-S2 when multi-target doc feature is ready.
+    The number of universally administered MAC address can be configured using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES`.
+
+    If the number of universal MAC addresses is one, only one interface (Wi-Fi Station) receive a universally administered MAC address. This is generated by adding 0 to the base MAC address. The remaining interface (Wi-Fi SoftAP) receive a local MAC address. This is derived from the universal Wi-Fi station.
+
+    If the number of universal MAC addresses is two, both interfaces (Wi-Fi Station, Wi-Fi SoftAP) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the final octet of the base MAC address.
+
+    When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 1 or 2 per device.)
 
 Chip version
 ------------

docs/zh_CN/api-reference/system/ota.rst

@@ -177,14 +177,17 @@ Kconfig 中的 :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` 可以帮助用户
 
   - ESP32 中版本号存储在 eFuse 的 ``EFUSE_BLK3_RDATA4_REG`` 里（若 eFuse 的位烧写为 1，则永远无法恢复为 0）。寄存器设置了多少位，应用程序的安全版本号就为多少。
 
+
+.. _secure-ota-updates:
+
+没有安全启动的安全 OTA 升级
+---------------------------
+
+即便硬件安全启动没有使能，也可验证已签名的 OTA 升级
+
 .. only:: esp32
 
-  .. _secure-ota-updates:
-
-  没有安全启动的安全 OTA 升级
-  ---------------------------
-
-  即便硬件安全启动没有使能，也可验证已签名的 OTA 升级，具体可参考 :ref:`signed-app-verify`。
+  具体可参考 :ref:`signed-app-verify`。
 
 
 OTA 工具 (otatool.py)