espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-07-30 18:57:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update api-reference chapters for C3

Browse Source 
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
This commit is contained in:
Marius Vikhammer
2021-02-23 09:31:29 +08:00
committed by No One
parent f12b571f82
commit fb82bdb9da
15 changed files with 110 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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
#include "rmt_caps.h"

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

@ -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

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

@ -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

2
components/wear_levelling/README.rst
View File

@ -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>`.

2
docs/conf_common.py
View File

@ -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,

1
docs/doxygen/Doxyfile_esp32c3
View File

@ -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

2
docs/en/api-reference/peripherals/ds.rst
View File

@ -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).

2
docs/en/api-reference/peripherals/hmac.rst
View File

@ -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] = { ... };

4
docs/en/api-reference/peripherals/index.rst
View File

@ -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>

37
docs/en/api-reference/protocols/esp_spi_slave_protocol.rst
View File

@ -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
------------

6
docs/en/api-reference/protocols/esp_tls.rst
View File

@ -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.

99
docs/en/api-reference/storage/sdmmc.rst
View File

@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^

7
docs/en/api-reference/storage/vfs.rst
View File

@ -1,12 +1,5 @@
.. include:: ../../../../components/vfs/README.rst
Application Example
-------------------
`Instructions`_
.. _Instructions: ../../template.html
API Reference
-------------

4
docs/zh_CN/api-reference/peripherals/index.rst
View File

@ -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>

2
tools/mass_mfg/docs/README.rst
View File

@ -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::