Merge branch 'docs/update_CN_trans_api_reference' into 'master'

Update CN translation for ESP-IDF (nvs_flash; sdmmc; spi_flash; spiffs)

Closes DOC-1901

See merge request espressif/esp-idf!15121

Author: Charlotudy

docs/en/api-reference/storage/fatfs.rst

@@ -84,4 +84,3 @@ They provide implementation of disk I/O functions for SD/MMC cards and can be re
 .. doxygenfunction:: ff_diskio_register_wl_partition
 .. doxygenfunction:: ff_diskio_register_raw_partition
 
-

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

@@ -14,7 +14,8 @@ Storage API
     SPI Flash and Partition APIs <spi_flash>
     SPIFFS Filesystem <spiffs>
     Virtual Filesystem <vfs>
-    Wear Levelling <wear-levelling>
+    Wear Levelling API <wear-levelling>
+
 
 
 Code examples for this API section are provided in the :example:`storage` directory of ESP-IDF examples.

docs/en/api-reference/storage/nvs_flash.rst

@@ -8,7 +8,6 @@ Introduction
 
 Non-volatile storage (NVS) library is designed to store key-value pairs in flash. This section introduces some concepts used by NVS.
 
-
 Underlying storage
 ^^^^^^^^^^^^^^^^^^
 
@@ -32,14 +31,14 @@ NVS operates on key-value pairs. Keys are ASCII strings; the maximum key length
 
 .. note::
 
-    String values are currently limited to 4000 bytes. This includes the null terminator. Blob values are limited to 508000 bytes or 97.6% of the partition size - 4000 bytes, whichever is lower.
+    String values are currently limited to 4000 bytes. This includes the null terminator. Blob values are limited to 508,000 bytes or 97.6% of the partition size - 4000 bytes, whichever is lower.
 
 Additional types, such as ``float`` and ``double`` might be added later.
 
 Keys are required to be unique. Assigning a new value to an existing key works as follows:
 
--  if the new value is of the same type as the old one, value is updated
--  if the new value has a different data type, an error is returned
+-  If the new value is of the same type as the old one, value is updated.
+-  If the new value has a different data type, an error is returned.
 
 Data type check is also performed when reading a value. An error is returned if the data type of the read operation does not match the data type of the value.
 
@@ -80,7 +79,7 @@ NVS Encryption
 
 Data stored in NVS partitions can be encrypted using AES-XTS in the manner similar to the one mentioned in disk encryption standard IEEE P1619. For the purpose of encryption, each entry is treated as one `sector` and relative address of the entry (w.r.t. partition-start) is fed to the encryption algorithm as `sector-number`. The NVS Encryption can be enabled by enabling :ref:`CONFIG_NVS_ENCRYPTION`. The keys required for NVS encryption are stored in yet another partition, which is protected using :doc:`Flash Encryption <../../security/flash-encryption>`. Therefore, enabling :doc:`Flash Encryption <../../security/flash-encryption>` is a prerequisite for NVS encryption.
 
-The NVS Encryption is enabled by default when :doc:`Flash Encryption <../../security/flash-encryption>` is enabled. This is done because WiFi driver stores credentials (like SSID and passphrase) in the default NVS partition. It is important to encrypt them as default choice if platform level encryption is already enabled.
+The NVS Encryption is enabled by default when :doc:`Flash Encryption <../../security/flash-encryption>` is enabled. This is done because Wi-Fi driver stores credentials (like SSID and passphrase) in the default NVS partition. It is important to encrypt them as default choice if platform level encryption is already enabled.
 
 For using NVS encryption, the partition table must contain the :ref:`nvs_key_partition`. Two partition tables containing the :ref:`nvs_key_partition` are provided for NVS encryption under the partition table option (menuconfig->Partition Table). They can be selected with the project configuration menu (``idf.py menuconfig``). Please refer to the example :example:`security/flash_encryption` for how to configure and use NVS encryption feature.
 
@@ -96,18 +95,18 @@ NVS key partition
 ::
 
     +-----------+--------------+-------------+----+
-    |              XTS encryption key(32)         |
+    |              XTS encryption key (32)        |
     +---------------------------------------------+
     |              XTS tweak key (32)             |
     +---------------------------------------------+
-    |                  CRC32(4)                   |
+    |                  CRC32 (4)                  |
     +---------------------------------------------+
 
 The XTS encryption keys in the :ref:`nvs_key_partition` can be generated in one of the following two ways.
 
 1. Generate the keys on the ESP chip:
 
-    When NVS encryption is enabled the :cpp:func:`nvs_flash_init` API function can be used to initialize the encrypted default NVS partition. The API function internally generates the XTS encryption keys on the ESP chip. The API function finds the first :ref:`nvs_key_partition`. Then the API function automatically generates and stores the nvs keys in that partition by making use of the :cpp:func:`nvs_flash_generate_keys` API function provided by :component_file:`nvs_flash/include/nvs_flash.h`. New keys are generated and stored only when the respective key partiton is empty. The same key partition can then be used to read the security configurations for initializing a custom encrypted NVS partition with help of :cpp:func:`nvs_flash_secure_init_partition`.
+    When NVS encryption is enabled the :cpp:func:`nvs_flash_init` API function can be used to initialize the encrypted default NVS partition. The API function internally generates the XTS encryption keys on the ESP chip. The API function finds the first :ref:`nvs_key_partition`. Then the API function automatically generates and stores the NVS keys in that partition by making use of the :cpp:func:`nvs_flash_generate_keys` API function provided by :component_file:`nvs_flash/include/nvs_flash.h`. New keys are generated and stored only when the respective key partiton is empty. The same key partition can then be used to read the security configurations for initializing a custom encrypted NVS partition with help of :cpp:func:`nvs_flash_secure_init_partition`.
 
     The API functions :cpp:func:`nvs_flash_secure_init` and :cpp:func:`nvs_flash_secure_init_partition` do not generate the keys internally. When these API functions are used for initializing encrypted NVS partitions, the keys can be generated after startup using the :cpp:func:`nvs_flash_generate_keys` API function provided by ``nvs_flash.h``. The API function will then write those keys onto the key-partition in encrypted form.
 
@@ -178,7 +177,7 @@ You can find code examples in the :example:`storage` directory of ESP-IDF exampl
 
 :example:`storage/nvs_rw_value_cxx`
 
-  This example does exactly the same as :example:`storage/nvs_rw_value`, except that it uses the C++ nvs handle class.
+  This example does exactly the same as :example:`storage/nvs_rw_value`, except that it uses the C++ NVS handle class.
 
 Internals
 ---------
@@ -378,5 +377,3 @@ API Reference
 .. include-build-file:: inc/nvs_flash.inc
 
 .. include-build-file:: inc/nvs.inc
-
-

docs/en/api-reference/storage/sdmmc.rst

@@ -74,22 +74,30 @@ An example which combines the SDMMC driver with the FATFS library is provided in
 
     For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
 
-    =========================================================================  =================================  =================================
-    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`
-    =========================================================================  =================================  =================================
+    .. list-table::
+       :widths: 55 25 20
+       :header-rows: 1
+
+       * - 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^

docs/en/api-reference/storage/spi_flash.rst

@@ -7,7 +7,7 @@ Overview
 --------
 The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in the external flash. The spi_flash component also has higher-level API functions which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`.
 
-Different from the API before IDF v4.0, the functionality of esp_flash_* APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access to external flashes chips connected to not only SPI0/1 but also other SPI buses like SPI2.
+Different from the API before IDF v4.0, the functionality of `esp_flash_*` APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access to external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.
 
 .. note::
 
@@ -20,7 +20,7 @@ Different from the API before IDF v4.0, the functionality of esp_flash_* APIs is
     Flash APIs after IDF v4.0 are no longer *atomic*. A writing operation during another on-going read operation, on the overlapped flash address, may cause the return data from the read operation to be partly same as before, and partly updated as new written.
 
 
-Kconfig option :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` can be used to switch ``spi_flash_*`` functions back to the implementation before IDF v4.0. However, the code size may get bigger if you use the new API and the old API the same time.
+Kconfig option :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` can be used to switch ``spi_flash_*`` functions back to the implementation before ESP-IDF v4.0. However, the code size may get bigger if you use the new API and the old API at the same time.
 
 Encrypted reads and writes use the old implementation, even if :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` is not enabled. As such, encrypted flash operations are only supported with the main flash chip (and not with other flash chips, that is on SPI1 with different CS, or on other SPI buses). Reading through cache is only supported on the main flash, which is determined by the HW.
 
@@ -96,7 +96,7 @@ Concurrency Constraints for flash on SPI1
 
 .. attention::
 
-   The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI Flash driver). Hence, calling SPI Flash API on SPI1 bus (including the main flash) will cause significant influence to the whole system. See :doc:`spi_flash_concurrency` for more details.
+   The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI flash driver). Hence, calling SPI Flash API on SPI1 bus (including the main flash) will cause significant influence to the whole system. See :doc:`spi_flash_concurrency` for more details.
 
 .. _flash-partition-apis:
 
@@ -147,11 +147,12 @@ Memory mapping API are declared in ``esp_spi_flash.h`` and ``esp_partition.h``:
 Differences between :cpp:func:`spi_flash_mmap` and :cpp:func:`esp_partition_mmap` are as follows:
 
 - :cpp:func:`spi_flash_mmap` must be given a {IDF_TARGET_CACHE_SIZE} aligned physical address.
-- :cpp:func:`esp_partition_mmap` may be given any arbitrary offset within the partition, it will adjust the returned pointer to mapped memory as necessary
+- :cpp:func:`esp_partition_mmap` may be given any arbitrary offset within the partition, it will adjust the returned pointer to mapped memory as necessary.
 
 Note that since memory mapping happens in pages, it may be possible to read data outside of the partition provided to ``esp_partition_mmap``, regardless of the partition boundary.
 
-.. note:: mmap is supported by cache, so it can only be used on main flash.
+.. note:: 
+    mmap is supported by cache, so it can only be used on main flash.
 
 SPI Flash Implementation
 ------------------------
@@ -219,13 +220,13 @@ In order to perform some flash operations, it is necessary to make sure that bot
 - In a single-core setup, the SDK does it by disabling interrupts/scheduler before performing the flash operation.
 - In a dual-core setup, this is slightly more complicated as the SDK needs to make sure that the other CPU is not running any code from flash.
 
-When SPI flash API is called on CPU A (can be PRO or APP), start the spi_flash_op_block_func function on CPU B using the esp_ipc_call API. This API wakes up a high priority task on CPU B and tells it to execute a given function, in this case, spi_flash_op_block_func. This function disables cache on CPU B and signals that the cache is disabled by setting the s_flash_op_can_start flag. Then the task on CPU A disables cache as well and proceeds to execute flash operation.
+When SPI flash API is called on CPU A (can be PRO or APP), start the ``spi_flash_op_block_func`` function on CPU B using the ``esp_ipc_call`` API. This API wakes up a high priority task on CPU B and tells it to execute a given function, in this case, ``spi_flash_op_block_func``. This function disables cache on CPU B and signals that the cache is disabled by setting the ``s_flash_op_can_start`` flag. Then the task on CPU A disables cache as well and proceeds to execute flash operation.
 
 While a flash operation is running, interrupts can still run on CPUs A and B. It is assumed that all interrupt code is placed into RAM. Once the interrupt allocation API is added, a flag should be added to request the interrupt to be disabled for the duration of a flash operations.
 
-Once the flash operation is complete, the function on CPU A sets another flag, s_flash_op_complete, to let the task on CPU B know that it can re-enable cache and release the CPU. Then the function on CPU A re-enables the cache on CPU A as well and returns control to the calling code.
+Once the flash operation is complete, the function on CPU A sets another flag, ``s_flash_op_complete``, to let the task on CPU B know that it can re-enable cache and release the CPU. Then the function on CPU A re-enables the cache on CPU A as well and returns control to the calling code.
 
-Additionally, all API functions are protected with a mutex (s_flash_op_mutex).
+Additionally, all API functions are protected with a mutex (``s_flash_op_mutex``).
 
 In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need to disable both caches, so that no inter-CPU communication can take place.
 

docs/en/api-reference/storage/spiffs.rst

@@ -112,7 +112,6 @@ To flash the image onto {IDF_TARGET_NAME} at offset 0x110000, run::
 
     python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
 
-
 Notes on which SPIFFS tool to use
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~