Merge branch 'doc/c3_system_api' into 'master'

docs: update system api reference chapters for C3

Closes IDF-2327 and IDF-2320

See merge request espressif/esp-idf!12730

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

@@ -19,6 +19,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

@@ -19,9 +19,9 @@ Line editing
 
 Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key.
 
-.. note:: 
+.. 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.
 
@@ -148,7 +148,7 @@ Initialize console REPL environment
 
 To establish a basic REPL environment, ``console`` component provides several useful APIs, combining those functions described above.
 
-In a typical application, you only need to call :cpp:func:`esp_console_new_repl_uart` to initialize the REPL environment based on UART device, including driver install, basic console configuration, spawning a thread to do REPL task and register several useful commands (e.g. `help`). 
+In a typical application, you only need to call :cpp:func:`esp_console_new_repl_uart` to initialize the REPL environment based on UART device, including driver install, basic console configuration, spawning a thread to do REPL task and register several useful commands (e.g. `help`).
 
 After that, you can register your own commands with :cpp:func:`esp_console_cmd_register`. The REPL environment keeps in init state until you call :cpp:func:`esp_console_start_repl`.
 

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
@@ -35,9 +36,9 @@ Example to tune the stack size of the pthread:
 The API can also be used for inheriting the settings across threads. For example:
 
 .. code-block:: c
-       
+
     void * my_thread2(void * p)
-    {   
+    {
         /* This thread will inherit the stack size of 4K */
         printf("In my_thread2\n");
 

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
+
+  Multicore issues
+  ----------------
 
-Peripherals that can generate interrupts can be divided in two types:
+  Peripherals that can generate interrupts can be divided in two types:
 
-  - 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.
+    - External peripherals, within the {IDF_TARGET_NAME} but outside the Xtensa cores themselves. Most {IDF_TARGET_NAME} peripherals are of this type.
+    - Internal peripherals, part of the Xtensa CPU cores themselves.
 
-Interrupt handling differs slightly between these two types of peripherals.
+  Interrupt handling differs slightly between these two types of peripherals.
 
-Internal peripheral interrupts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  Internal peripheral interrupts
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Each Xtensa CPU core has its own set of six internal peripherals:
+  Each Xtensa CPU core has its own set of six internal peripherals:
 
-  - Three timer comparators
-  - A performance monitor
-  - Two software interrupts.
+    - Three timer comparators
+    - A performance monitor
+    - Two software interrupts.
 
-Internal interrupt sources are defined in esp_intr_alloc.h as ``ETS_INTERNAL_*_INTR_SOURCE``.
+  Internal interrupt sources are defined in esp_intr_alloc.h as ``ETS_INTERNAL_*_INTR_SOURCE``.
 
-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).
+  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).
 
-External Peripheral Interrupts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  External Peripheral Interrupts
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The remaining interrupt sources are from external peripherals. These are defined in soc/soc.h as ``ETS_*_INTR_SOURCE``.
+  The remaining interrupt sources are from external peripherals. These are defined in soc/soc.h as ``ETS_*_INTR_SOURCE``.
 
-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.
+  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.
 
-- 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().
+  - 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.
+  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,31 +4,31 @@ 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 
+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.
 
-A given function can be executed on a particular core by calling 
-:cpp:func:`esp_ipc_call` or :cpp:func:`esp_ipc_call_blocking`. IPC is 
+A given function can be executed on a particular core by calling
+:cpp:func:`esp_ipc_call` or :cpp:func:`esp_ipc_call_blocking`. IPC is
 implemented via two high priority FreeRTOS tasks pinned to each CPU known as
-the IPC Tasks. The two IPC Tasks remain inactive (blocked) until 
-:cpp:func:`esp_ipc_call` or :cpp:func:`esp_ipc_call_blocking` is called. When 
-an IPC Task of a particular core is unblocked, it will preempt the current 
-running task on that core and execute a given function. 
+the IPC Tasks. The two IPC Tasks remain inactive (blocked) until
+:cpp:func:`esp_ipc_call` or :cpp:func:`esp_ipc_call_blocking` is called. When
+an IPC Task of a particular core is unblocked, it will preempt the current
+running task on that core and execute a given function.
 
 Usage
 -----
 
 :cpp:func:`esp_ipc_call` unblocks the IPC task on a particular core to execute
 a given function. The task that calls :cpp:func:`esp_ipc_call` will be blocked
-until the IPC Task begins execution of the given function. 
+until the IPC Task begins execution of the given function.
 :cpp:func:`esp_ipc_call_blocking` is similar but will block the calling task
 until the IPC Task has completed execution of the given function.
- 
-Functions executed by IPCs must be functions of type 
-`void func(void *arg)`. To run more complex functions which require a larger 
-stack, the IPC tasks' stack size can be configured by modifying 
+
+Functions executed by IPCs must be functions of type
+`void func(void *arg)`. To run more complex functions which require a larger
+stack, the IPC tasks' stack size can be configured by modifying
 :ref:`CONFIG_ESP_IPC_TASK_STACK_SIZE` in `menuconfig`. The IPC API is protected by a
 mutex hence simultaneous IPC calls are not possible.
 

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,16 +195,19 @@ 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.
 
-.. only:: esp32
 
-  .. _secure-ota-updates:
+.. _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 Without Secure boot
-  --------------------------------------
+  For more information refer to :ref:`signed-app-verify`
 
-  The verification of signed OTA updates can be performed even without enabling hardware secure boot. For doing so, refer :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
+
+    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.
 
-   Add illustration for ESP32-S2 when multi-target doc feature is ready.
+    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

@@ -43,17 +43,17 @@ OTA 数据分区是两个 0x2000 字节大小的 flash 扇区，防止写入时
 状态控制了选取启动应用程序的过程：
 
 =============================  ========================================================
-状态                            启动加载器选取启动应用程序的限制               
+状态                            启动加载器选取启动应用程序的限制
 =============================  ========================================================
- ESP_OTA_IMG_VALID             没有限制，可以选取。                                      
- ESP_OTA_IMG_UNDEFINED         没有限制，可以选取。                                      
- ESP_OTA_IMG_INVALID           不会选取。                                              
- ESP_OTA_IMG_ABORTED           不会选取。                                              
+ ESP_OTA_IMG_VALID             没有限制，可以选取。
+ ESP_OTA_IMG_UNDEFINED         没有限制，可以选取。
+ ESP_OTA_IMG_INVALID           不会选取。
+ ESP_OTA_IMG_ABORTED           不会选取。
  ESP_OTA_IMG_NEW               如使能 :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE`，
-                               则仅会选取一次。在启动加载器中，状态立即变为                  
-                               ``ESP_OTA_IMG_PENDING_VERIFY``。                       
+                               则仅会选取一次。在启动加载器中，状态立即变为
+                               ``ESP_OTA_IMG_PENDING_VERIFY``。
  ESP_OTA_IMG_PENDING_VERIFY    如使能 :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE`，
-                               则不会选取，状态变为``ESP_OTA_IMG_ABORTED``。             
+                               则不会选取，状态变为``ESP_OTA_IMG_ABORTED``。
 =============================  ========================================================
 
 如果 :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` 没有使能（默认情况），则 :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` 和 :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` 为可选功能，``ESP_OTA_IMG_NEW`` 和 ``ESP_OTA_IMG_PENDING_VERIFY`` 不会使用。
@@ -177,16 +177,19 @@ Kconfig 中的 :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` 可以帮助用户
 
   - ESP32 中版本号存储在 eFuse 的 ``EFUSE_BLK3_RDATA4_REG`` 里（若 eFuse 的位烧写为 1，则永远无法恢复为 0）。寄存器设置了多少位，应用程序的安全版本号就为多少。
 
-.. only:: esp32
 
-  .. _secure-ota-updates:
+.. _secure-ota-updates:
+
+没有安全启动的安全 OTA 升级
+---------------------------
+
+即便硬件安全启动没有使能，也可验证已签名的 OTA 升级
+
+.. only:: esp32
 
-  没有安全启动的安全 OTA 升级
-  ---------------------------
+  具体可参考 :ref:`signed-app-verify`。
 
-  即便硬件安全启动没有使能，也可验证已签名的 OTA 升级，具体可参考 :ref:`signed-app-verify`。
 
-    
 OTA 工具 (otatool.py)
 ---------------------