From 6334b5e56f357d17e198a56548d6aa0dbb6dc1f4 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Tue, 23 Feb 2021 09:31:29 +0800 Subject: [PATCH] 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 --- components/soc/esp32c3/include/soc/soc_caps.h | 10 +- components/soc/esp32s2/include/soc/soc_caps.h | 2 + components/soc/esp32s3/include/soc/soc_caps.h | 2 + components/wear_levelling/README.rst | 2 +- docs/conf_common.py | 2 + docs/doxygen/Doxyfile_esp32c3 | 1 + docs/en/api-reference/peripherals/ds.rst | 2 +- docs/en/api-reference/peripherals/hmac.rst | 4 +- docs/en/api-reference/peripherals/index.rst | 4 +- .../protocols/esp_spi_slave_protocol.rst | 37 +++---- docs/en/api-reference/protocols/esp_tls.rst | 12 +-- docs/en/api-reference/storage/sdmmc.rst | 99 ++++++++++--------- docs/en/api-reference/storage/vfs.rst | 7 -- .../zh_CN/api-reference/peripherals/index.rst | 4 +- tools/mass_mfg/docs/README.rst | 30 +++--- 15 files changed, 110 insertions(+), 108 deletions(-) diff --git a/components/soc/esp32c3/include/soc/soc_caps.h b/components/soc/esp32c3/include/soc/soc_caps.h index e0840852db..5fe805dfc8 100644 --- a/components/soc/esp32c3/include/soc/soc_caps.h +++ b/components/soc/esp32c3/include/soc/soc_caps.h @@ -5,10 +5,12 @@ #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_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 /*-------------------------- DAC CAPS ----------------------------------------*/ #define SOC_DAC_PERIPH_NUM 0 diff --git a/components/soc/esp32s2/include/soc/soc_caps.h b/components/soc/esp32s2/include/soc/soc_caps.h index 92466c45dd..cd0c2d079a 100644 --- 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 diff --git a/components/soc/esp32s3/include/soc/soc_caps.h b/components/soc/esp32s3/include/soc/soc_caps.h index 0c83b28670..d3b5eb2c45 100644 --- 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 diff --git a/components/wear_levelling/README.rst b/components/wear_levelling/README.rst index 4623bf12b4..c05a2f2667 100644 --- 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 `. diff --git a/docs/conf_common.py b/docs/conf_common.py index 54fe634b74..9737a03ed5 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -209,6 +209,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, diff --git a/docs/doxygen/Doxyfile_esp32c3 b/docs/doxygen/Doxyfile_esp32c3 index 6a349aecc6..17262969ea 100644 --- 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 diff --git a/docs/en/api-reference/peripherals/ds.rst b/docs/en/api-reference/peripherals/ds.rst index 73d4cc413c..125b9be28e 100644 --- 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). diff --git a/docs/en/api-reference/peripherals/hmac.rst b/docs/en/api-reference/peripherals/hmac.rst index 7a79f2f9dc..ae594443ef 100644 --- a/docs/en/api-reference/peripherals/hmac.rst +++ b/docs/en/api-reference/peripherals/hmac.rst @@ -58,7 +58,7 @@ Each key has a corresponding eFuse parameter *key purpose* determining for which This is to prevent the usage of a key for a different function than originally intended. To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the *key purpose* (see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__]). -Before the HMAC key calculation, the HMAC module looks up the purpose of the provided key block. +Before the HMAC key calculation, the HMAC module looks up the purpose of the provided key block. The calculation only proceeds if the provided key purpose matches the purpose stored in the eFuses of the key block provided by the ID. HMAC Generation for Software @@ -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] = { ... }; diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 803033f706..a58bd3ce80 100644 --- 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 GPIO (including RTC low power I/O) :SOC_DEDICATED_GPIO_SUPPORTED: Dedicated GPIO - :esp32s2: HMAC - :esp32s2: Digital Signature + :SOC_HMAC_SUPPORTED: HMAC + :SOC_DIG_SIGN_SUPPORTED: Digital Signature I2C I2S LED Control diff --git a/docs/en/api-reference/protocols/esp_spi_slave_protocol.rst b/docs/en/api-reference/protocols/esp_spi_slave_protocol.rst index 4a66a562c4..608a714ba9 100644 --- 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 ------------ diff --git a/docs/en/api-reference/protocols/esp_tls.rst b/docs/en/api-reference/protocols/esp_tls.rst index 21a9ef43b3..f417ce4774 100644 --- a/docs/en/api-reference/protocols/esp_tls.rst +++ b/docs/en/api-reference/protocols/esp_tls.rst @@ -4,8 +4,8 @@ ESP-TLS Overview -------- -The ESP-TLS component provides a simplified API interface for accessing the commonly used TLS functionality. -It supports common scenarios like CA certification validation, SNI, ALPN negotiation, non-blocking connection among others. +The ESP-TLS component provides a simplified API interface for accessing the commonly used TLS functionality. +It supports common scenarios like CA certification validation, SNI, ALPN negotiation, non-blocking connection among others. All the configuration can be specified in the ``esp_tls_cfg_t`` data structure. Once done, TLS communication can be conducted using the following APIs: * :cpp:func:`esp_tls_conn_new`: for opening a new TLS connection. @@ -13,7 +13,7 @@ All the configuration can be specified in the ``esp_tls_cfg_t`` data structure. * :cpp:func:`esp_tls_conn_write`: for writing into the connection. * :cpp:func:`esp_tls_conn_delete`: for freeing up the connection. -Any application layer protocol like HTTP1, HTTP2 etc can be executed on top of this layer. +Any application layer protocol like HTTP1, HTTP2 etc can be executed on top of this layer. Application Example ------------------- @@ -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 `. 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 `. - .. 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.`. - 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. diff --git a/docs/en/api-reference/storage/sdmmc.rst b/docs/en/api-reference/storage/sdmmc.rst index b3131a46a1..67946eaba3 100644 --- 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,79 +16,80 @@ SDMMC and SD SPI host drivers (:component_file:`driver/include/driver/sdmmc_host For functions used to initialize and configure: -.. only:: esp32 +.. list:: - - SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>` - - - SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>` + :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>` - The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands. +.. only:: SOC_SDMMC_HOST_SUPPORTED - 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. + 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 - ------------------- +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. +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 + ------------------ + + The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any. + Using API with SD memory cards + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Protocol layer API - ------------------ - - The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any. + 1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`. + 2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes. + 3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure. + 4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver. - Using API with SD memory cards - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Using API with eMMC chips + ^^^^^^^^^^^^^^^^^^^^^^^^^ - 1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`. - 2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes. - 3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure. - 4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver. + From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver. + + To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section. - Using API with eMMC chips - ^^^^^^^^^^^^^^^^^^^^^^^^^ + Using API with SDIO cards + ^^^^^^^^^^^^^^^^^^^^^^^^^ - From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver. + Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode. - To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section. + During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card: + 1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register. + 2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode. + 3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register. - Using API with SDIO cards - ^^^^^^^^^^^^^^^^^^^^^^^^^ + In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`. - Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode. + For card configuration and data transfer, choose the pair of functions relevant to your case from the table below. - During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card: + ========================================================================= ================================= ================================= + Action Read Function Write Function + ========================================================================= ================================= ================================= + Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte` + Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes` + Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks` + ========================================================================= ================================= ================================= - 1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register. - 2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode. - 3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register. + SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts. - In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`. + If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`. - For card configuration and data transfer, choose the pair of functions relevant to your case from the table below. + .. only:: esp32 - ========================================================================= ================================= ================================= - Action Read Function Write Function - ========================================================================= ================================= ================================= - Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte` - Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes` - Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks` - ========================================================================= ================================= ================================= - - SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts. - - If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`. - - .. only:: esp32 - - There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32 - SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`. + There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32 + SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`. Combo (memory + IO) cards ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/storage/vfs.rst b/docs/en/api-reference/storage/vfs.rst index 480665165a..c7311d58ea 100644 --- 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 ------------- diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 97710cfa07..ce5b7d5048 100644 --- 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 GPIO (包括 RTC 低功耗 I/O) :SOC_DEDICATED_GPIO_SUPPORTED: 专用 GPIO - :esp32s2: HMAC - :esp32s2: Digital Signature + :SOC_HMAC_SUPPORTED: HMAC + :SOC_DIG_SIGN_SUPPORTED: Digital Signature I2C I2S LED Control diff --git a/tools/mass_mfg/docs/README.rst b/tools/mass_mfg/docs/README.rst index c318955b12..6ed10a22a0 100644 --- 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: + - `Python `_ .. note:: @@ -36,7 +36,7 @@ Prerequisites Workflow -------- -.. blockdiag:: +.. blockdiag:: blockdiag { A [label = "CSV Configuration file"]; @@ -51,13 +51,13 @@ CSV Configuration File ---------------------- This file contains the configuration of the device to be flashed. - -The data in the configuration file has the following format (the `REPEAT` tag is optional):: + +The data in the configuration file has the following format (the `REPEAT` tag is optional):: name1,namespace, <-- First entry should be of type "namespace" key1,type1,encoding1 key2,type2,encoding2,REPEAT - name2,namespace, + name2,namespace, key3,type3,encoding3 key4,type4,encoding4 @@ -88,11 +88,11 @@ Master Value CSV File --------------------- This file contains details of the devices to be flashed. Each line in this file corresponds to a device instance. - + The data in the master value CSV file has the following format:: key1,key2,key3,..... - value1,value2,value3,.... + value1,value2,value3,.... .. note:: The first line in the file should always contain the ``key`` names. All the keys from the configuration file should be present here in the **same order**. This file can have additional columns (keys). The additional keys will be treated as metadata and would not be part of the final binary files. @@ -107,10 +107,10 @@ Data value is the value of data corresponding to the key. Below is a sample example of a master value CSV file:: - id,firmware_key,serial_no,device_no - 1,1a2b3c4d5e6faabb,A1,101 - 2,1a2b3c4d5e6fccdd,,102 - 3,1a2b3c4d5e6feeff,,103 + id,firmware_key,serial_no,device_no + 1,1a2b3c4d5e6faabb,A1,101 + 2,1a2b3c4d5e6fccdd,,102 + 3,1a2b3c4d5e6feeff,,103 .. note:: *If the 'REPEAT' tag is present, a new master value CSV file will be created in the same folder as the input Master CSV File with the values inserted at each line for the key with the 'REPEAT' tag*. @@ -157,16 +157,16 @@ Running the utility [--keyfile KEYFILE] [--inputkey INPUTKEY] [--outdir OUTDIR] conf values prefix size - + Positional Arguments: +--------------+----------------------------------------------------------------------+ | Parameter | Description | +==============+======================================================================+ - | conf | Path to configuration csv file to parse | + | conf | Path to configuration csv file to parse | +--------------+----------------------------------------------------------------------+ | values | Path to values csv file to parse | +--------------+----------------------------------------------------------------------+ - | prefix | Unique name for each output filename prefix | + | prefix | Unique name for each output filename prefix | +-----+--------------+----------------------------------------------------------------+ | size | Size of NVS partition in bytes | | | (must be multiple of 4096) | @@ -231,7 +231,7 @@ You can run the utility to encrypt factory images for each device using the comm | --outdir OUTDIR | Output directory to store files created. | | | (Default: current directory) | +--------------------+----------------------------------------------------------------------+ - + You can run the utility to generate only encryption keys using the command below:: python mfg_gen.py generate-key