docs: update api-reference chapters for C3

Checked and updated the following chapters: * api-reference/network * api-reference/protocols * api-reference/provisioning * api-reference/storage * api-reference/peripherals/ds * api-reference/peripherals/hmac * api-reference/peripherals/secure_element
2025-08-01 11:44:31 +02:00 · 2021-02-23 09:31:29 +08:00
parent f12b571f82
commit fb82bdb9da
15 changed files with 110 additions and 108 deletions
--- a/components/soc/esp32c3/include/soc/soc_caps.h
+++ b/components/soc/esp32c3/include/soc/soc_caps.h
@@ -9,6 +9,8 @@
 #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

 #include "rmt_caps.h"

--- a/components/soc/esp32s2/include/soc/soc_caps.h
+++ b/components/soc/esp32s2/include/soc/soc_caps.h
@@ -48,6 +48,8 @@
 #define SOC_ULP_SUPPORTED               1
 #define SOC_RTC_SLOW_MEM_SUPPORTED      1
 #define SOC_CCOMP_TIMER_SUPPORTED       1
+#define SOC_DIG_SIGN_SUPPORTED          1
+#define SOC_HMAC_SUPPORTED              1
 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3

 #define SOC_CACHE_SUPPORT_WRAP          1
--- a/components/soc/esp32s3/include/soc/soc_caps.h
+++ b/components/soc/esp32s3/include/soc/soc_caps.h
@@ -15,6 +15,8 @@
 #define SOC_ULP_SUPPORTED               1
 #define SOC_RTC_SLOW_MEM_SUPPORTED      1
 #define SOC_CCOMP_TIMER_SUPPORTED       1
+#define SOC_DIG_SIGN_SUPPORTED          1
+#define SOC_HMAC_SUPPORTED              1
 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3


--- a/components/wear_levelling/README.rst
+++ b/components/wear_levelling/README.rst
@@ -5,7 +5,7 @@ Wear Levelling API

 Overview
 --------
-Most of flash memory and especially SPI flash that is used in ESP32 has a sector-based organization and also has a limited number of erase/modification cycles per memory sector. The wear levelling component helps to distribute wear and tear among sectors more evenly without requiring any attention from the user.
+Most of flash memory and especially SPI flash that is used in {IDF_TARGET_NAME} has a sector-based organization and also has a limited number of erase/modification cycles per memory sector. The wear levelling component helps to distribute wear and tear among sectors more evenly without requiring any attention from the user.

 The wear levelling component provides API functions related to reading, writing, erasing, and memory mapping of data in external SPI flash through the partition component. The component also has higher-level API functions which work with the FAT filesystem defined in :doc:`FAT filesystem </api-reference/storage/fatfs>`.

--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -208,6 +208,8 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
                            'SOC_TOUCH_SENSOR_NUM':TOUCH_SENSOR_DOCS,
                            'SOC_ULP_SUPPORTED':ULP_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'],
                            'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS,
                            'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS,
                            'esp32':ESP32_DOCS,
--- a/docs/doxygen/Doxyfile_esp32c3
+++ b/docs/doxygen/Doxyfile_esp32c3
@@ -1,3 +1,4 @@
 INPUT += \
         $(IDF_PATH)/components/driver/esp32c3/include/driver/temp_sensor.h \
+         $(IDF_PATH)/components/esp32s2/include/esp_ds.h \
         $(IDF_PATH)/components/esp32c3/include/esp_hmac.h
--- a/docs/en/api-reference/peripherals/ds.rst
+++ b/docs/en/api-reference/peripherals/ds.rst
@@ -51,7 +51,7 @@ Once the calculation has finished, :cpp:func:`esp_ds_finish_sign` can be called
 Configure the DS peripheral for a TLS connection
 ------------------------------------------------

-The DS peripheral on ESP32-S2 chip must be configured before it can be used for a TLS connection.
+The DS peripheral on {IDF_TARGET_NAME} chip must be configured before it can be used for a TLS connection.
 The configuration involves the following steps -

 1) Randomly generate a 256 bit value called the `Initialization Vector` (IV).
--- a/docs/en/api-reference/peripherals/hmac.rst
+++ b/docs/en/api-reference/peripherals/hmac.rst
@@ -115,7 +115,7 @@ We use `ets_efuse_write_key` to set physical key block 4 in the eFuse for the HM

 .. code-block:: c

-    #include "esp32s2/rom/efuse.h"
+    #include "{IDF_TARGET_PATH_NAME}/rom/efuse.h"

    const uint8_t key_data[32] = { ... };

--- a/docs/en/api-reference/peripherals/index.rst
+++ b/docs/en/api-reference/peripherals/index.rst
@@ -11,8 +11,8 @@ Peripherals API
    :SOC_DAC_PERIPH_NUM: DAC <dac>
    GPIO (including RTC low power I/O) <gpio>
    :SOC_DEDICATED_GPIO_SUPPORTED: Dedicated GPIO <dedic_gpio>
-    :esp32s2: HMAC <hmac>
-    :esp32s2: Digital Signature <ds>
+    :SOC_HMAC_SUPPORTED: HMAC <hmac>
+    :SOC_DIG_SIGN_SUPPORTED: Digital Signature <ds>
    I2C <i2c>
    I2S <i2s>
    LED Control <ledc>
--- a/docs/en/api-reference/protocols/esp_spi_slave_protocol.rst
+++ b/docs/en/api-reference/protocols/esp_spi_slave_protocol.rst
@@ -1,30 +1,31 @@
 ESP SPI Slave HD (Half Duplex) Mode Protocol
 ============================================

-.. note::
-    This protocol is only for ESP32-S2. The driver for other chip versions hasn't be developed
-    yet.
+.. only:: esp32
+
+    .. warning::
+        The driver for ESP32 hasn't been developed yet.

 .. _esp_spi_slave_caps:

 SPI Slave Capabilities of Espressif chips
 -----------------------------------------

-+--------------------+-------+----------+
-|                    | ESP32 | ESP32-S2 |
-+====================+=======+==========+
-| SPI Slave HD       | N     | Y (v2)   |
-+--------------------+-------+----------+
-| Tohost intr        |       | N        |
-+--------------------+-------+----------+
-| Frhost intr        |       | 2  \*    |
-+--------------------+-------+----------+
-| TX DMA             |       | Y        |
-+--------------------+-------+----------+
-| RX DMA             |       | Y        |
-+--------------------+-------+----------+
-| Shared   registers |       | 72       |
-+--------------------+-------+----------+
+--------------------+-------+----------+----------+
+|                    | ESP32 | ESP32-S2 | ESP32-C3 |
+====================+=======+==========+==========+
+| SPI Slave HD       | N     | Y (v2)   | Y (v2)   |
+--------------------+-------+----------+----------+
+| Tohost intr        |       | N        | N        |
+--------------------+-------+----------+----------+
+| Frhost intr        |       | 2  \*    | 2  \*    |
+--------------------+-------+----------+----------+
+| TX DMA             |       | Y        | Y        |
+--------------------+-------+----------+----------+
+| RX DMA             |       | Y        | Y        |
+--------------------+-------+----------+----------+
+| Shared   registers |       | 72       | 64       |
+--------------------+-------+----------+----------+

 Introduction
 ------------
--- a/docs/en/api-reference/protocols/esp_tls.rst
+++ b/docs/en/api-reference/protocols/esp_tls.rst
@@ -137,20 +137,18 @@ SSL/TLS libraries and with all respective configurations set to default.
                .use_secure_element = true,
            };

-.. only:: esp32s2
+.. only:: SOC_DIG_SIGN_SUPPORTED

    .. _digital-signature-with-esp-tls:

    Digital Signature with ESP-TLS
    ------------------------------
-    ESP-TLS provides support for using the Digital Signature (DS) with ESP32-S2.
+    ESP-TLS provides support for using the Digital Signature (DS) with {IDF_TARGET_NAME}.
    Use of the DS for TLS is supported only when ESP-TLS is used with mbedTLS (default stack) as its underlying SSL/TLS stack.
    For more details on Digital Signature, please refer to the :doc:`Digital Signature Documentation </api-reference/peripherals/ds>`. The technical details of Digital Signature such as
    how to calculate private key parameters can be found in *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
    The DS peripheral must be configured before it can be used to perform Digital Signature, see `Configure the DS Peripheral` in :doc:`Digital Signature </api-reference/peripherals/ds>`.

-    .. note:: As the DS peripheral support is only available for ESP32-S2, the idf-target should be set to ESP32-S2. See `Selecting the Target` in :doc:`build-system.</api-guides/build-system>`.
-
    The DS peripheral must be initlized with the required encrypted private key parameters (obtained when the DS peripheral is configured). ESP-TLS internally initializes the DS peripheral when
    provided with the required DS context (DS parameters). Please see the below code snippet for passing the DS context to esp-tls context. The DS context passed to the esp-tls context should not be freed till the TLS connection is deleted.

--- a/docs/en/api-reference/storage/sdmmc.rst
+++ b/docs/en/api-reference/storage/sdmmc.rst
@@ -8,7 +8,7 @@ Overview

 The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This is a protocol level driver built on top of SDMMC and SD SPI host drivers.

-SDMMC and SD SPI host drivers (:component_file:`driver/include/driver/sdmmc_host.h`) provide API functions for:
+SDMMC and SD SPI host drivers (:component_file:`driver/include/driver/sdmmc_host.h` and :component_file:`driver/include/driver/sdspi_host.h`) provide API functions for:

 - Sending commands to slave devices
 - Sending and receiving data
@@ -16,24 +16,25 @@ SDMMC and SD SPI host drivers (:component_file:`driver/include/driver/sdmmc_host

 For functions used to initialize and configure:

-.. only:: esp32
-
-    - SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>`
+.. list::

+    :SOC_SDMMC_HOST_SUPPORTED: - SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>`
    - SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>`


+.. only:: SOC_SDMMC_HOST_SUPPORTED
+
    The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands.

    The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.


-   Application Example
-   -------------------
-
-   An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
+Application Example
+-------------------

+An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.

+.. only:: SOC_SDMMC_HOST_SUPPORTED

    Protocol layer API
    ------------------
--- a/docs/en/api-reference/storage/vfs.rst
+++ b/docs/en/api-reference/storage/vfs.rst
@@ -1,12 +1,5 @@
 .. include:: ../../../../components/vfs/README.rst

-Application Example
-------------------
-
-`Instructions`_
-
-.. _Instructions: ../../template.html
-
 API Reference
 -------------

--- a/docs/zh_CN/api-reference/peripherals/index.rst
+++ b/docs/zh_CN/api-reference/peripherals/index.rst
@@ -10,8 +10,8 @@
    :SOC_DAC_PERIPH_NUM: DAC <dac>
    GPIO (包括 RTC 低功耗 I/O) <gpio>
    :SOC_DEDICATED_GPIO_SUPPORTED: 专用 GPIO <dedic_gpio>
-    :esp32s2: HMAC <hmac>
-    :esp32s2: Digital Signature <ds>
+    :SOC_HMAC_SUPPORTED: HMAC <hmac>
+    :SOC_DIG_SIGN_SUPPORTED: Digital Signature <ds>
    I2C <i2c>
    I2S <i2s>
    LED Control <ledc>
--- a/tools/mass_mfg/docs/README.rst
+++ b/tools/mass_mfg/docs/README.rst
@@ -24,7 +24,7 @@ Prerequisites
 	-	Linux / MacOS / Windows (standard distributions)

 * The following packages are needed to use this utility:
-	-	Python: <https://www.python.org/downloads/>
+	-	`Python <https://www.python.org/downloads/>`_

 .. note::