docs: translate networking.rst and storage.rst

docs/en/migration-guides/release-5.x/networking.rst

@@ -4,69 +4,64 @@ Networking
 :link_to_translation:`zh_CN:[中文]`
 
 Ethernet
-**********
+********
 
 esp_eth_ioctl() API
 -------------------
 
-:cpp:func:`esp_eth_ioctl` third argument could take `int` (`bool`) number as an input in some cases. However, it was not properly documented and, in addition, the number had to be "unnaturally" type casted to `void *` datatype to prevent compiler warnings as shown in below example:
+Previously, the :cpp:func:`esp_eth_ioctl` API had the following issues:
 
-.. highlight:: c
+    - The third parameter (which is of type ``void *``) would accept an ``int``/``bool`` type arguments (i.e., not pointers) as input in some cases. However, these cases were not documented properly.
+    - To pass ``int``/``bool`` type argument as the third parameter, the argument had to be "unnaturally" casted to a ``void *`` type, to prevent a compiler warning as demonstrated in the code snippet below. This casting could lead to misuse of the :cpp:func:`esp_eth_ioctl` function.
 
-::
+.. code-block:: c
 
     esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true);
 
-
-This could lead to misuse of the :cpp:func:`esp_eth_ioctl`. Therefore, ESP-IDF 5.0 unified usage of :cpp:func:`esp_eth_ioctl`. Its third argument now always acts as pointer to a memory location of specific type from/to where the configuration option is read/stored.
+Therefore, the usage of :cpp:func:`esp_eth_ioctl` is now unified. Arguments to the third parameter must be passed as pointers to a specific data type to/from where data will be stored/read by :cpp:func:`esp_eth_ioctl`. The code snippets below demonstrate the usage of :cpp:func:`esp_eth_ioctl`.
 
 Usage example to set Ethernet configuration:
 
-.. highlight:: c
-
-::
+.. code-block:: c
 
     eth_duplex_t new_duplex_mode = ETH_DUPLEX_HALF;
     esp_eth_ioctl(eth_handle, ETH_CMD_S_DUPLEX_MODE, &new_duplex_mode);
 
 Usage example to get Ethernet configuration:
 
-.. highlight:: c
-
-::
-
+.. code-block:: c
+    
     eth_duplex_t duplex_mode;
     esp_eth_ioctl(eth_handle, ETH_CMD_G_DUPLEX_MODE, &duplex_mode);
 
-
 KSZ8041/81 and LAN8720 Driver Update
 ------------------------------------
 
-KSZ8041/81 and LAN8720 Drivers were updated to support more devices (generations) from associated product family. The drivers are able to recognize particular chip number and its potential support by the driver.
+The KSZ8041/81 and LAN8720 drivers are updated to support more devices (i.e., generations) from their associated product families. The drivers can recognize particular chip numbers and their potential support by the driver.
 
-As a result, the specific "chip number" functions calls were replaced by generic ones as follows:
+As a result, the specific "chip number" functions calls are replaced by generic ones as follows:
 
-* `esp_eth_phy_new_ksz8041` and `esp_eth_phy_new_ksz8081` were removed, use :cpp:func:`esp_eth_phy_new_ksz80xx` instead
-* `esp_eth_phy_new_lan8720` was removed, use :cpp:func:`esp_eth_phy_new_lan87xx` instead
+* Removed ``esp_eth_phy_new_ksz8041()`` and ``esp_eth_phy_new_ksz8081()``, and use :cpp:func:`esp_eth_phy_new_ksz80xx` instead
+* Removed ``esp_eth_phy_new_lan8720()``, and use :cpp:func:`esp_eth_phy_new_lan87xx` instead
 
 
 ESP NETIF Glue Event Handlers
 -----------------------------
 
-``esp_eth_set_default_handlers()`` and ``esp_eth_clear_default_handlers()`` functions were removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If users have already followed the recommendation to fully initialize the Ethernet driver and network interface prior to registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Otherwise, users should ensure that they register the user event handlers as the last thing prior to starting the Ethernet driver.
+``esp_eth_set_default_handlers()`` and ``esp_eth_clear_default_handlers()`` functions are removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If you have already followed the suggestion to fully initialize the Ethernet driver and network interface before registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Otherwise, you may start the Ethernet driver right after they register the user event handler.
 
 PHY Address Auto-detect
 -----------------------
 
-Ethernet PHY address auto-detect function ``esp_eth_detect_phy_addr`` was renamed to :cpp:func:`esp_eth_phy_802_3_detect_phy_addr` and its header declaration was moved to :component_file:`esp_eth/include/esp_eth_phy_802_3.h`.
+The Ethernet PHY address auto-detect function ``esp_eth_detect_phy_addr()`` is renamed to :cpp:func:`esp_eth_phy_802_3_detect_phy_addr` and its header declaration is moved to :component_file:`esp_eth/include/esp_eth_phy_802_3.h`.
 
 
-SPI-Ethernet Modules Initialization
+SPI-Ethernet Module Initialization
 -----------------------------------
 
-The SPI-Ethernet Module's initialization has been simplified. The previous initialization process required you to manually allocate an SPI device using :cpp:func:`spi_bus_add_device` before instantiating the SPI-Ethernet MAC.
+The SPI-Ethernet Module initialization is now simplified. Previously, you had to manually allocate an SPI device using :cpp:func:`spi_bus_add_device` before instantiating the SPI-Ethernet MAC.
 
-Now, you no longer need to call :cpp:func:`spi_bus_add_device` as the allocation of the SPI device is done internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures were updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros have been updated to accept new input parameters. Refer to the :doc:`Ethernet API-Reference Guide<../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization 
+Now, you no longer need to call :cpp:func:`spi_bus_add_device` as SPI devices are allocated internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures are updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros are updated to accept new input parameters. Refer to :doc:`Ethernet API Reference Guide<../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization.
 
 
 .. _tcpip-adapter:
@@ -74,41 +69,40 @@ Now, you no longer need to call :cpp:func:`spi_bus_add_device` as the allocation
 TCP/IP Adapter
 *****************
 
-TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This page outlines migration from tcpip_adapter API to its successor :doc:`/api-reference/network/esp_netif`.
+The TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This section outlines migration from tcpip_adapter API to its successor :doc:`/api-reference/network/esp_netif`.
 
 
-Updating network connection code
+Updating Network Connection Code
 --------------------------------
 
 
-Network stack initialization
+Network Stack Initialization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Simply replace ``tcpip_adapter_init()`` with ``esp_netif_init()``. Please note that the :doc:`/api-reference/network/esp_netif` initialization API returns standard error code and the ``esp_netif_deinit()`` for un-initialization is available.
-
-Also replace ``#include "tcpip_adapter.h"`` with ``#include "esp_netif.h"``.
+- You may simply replace ``tcpip_adapter_init()`` with ``esp_netif_init()``. However, please should note that the ``esp_netif_init()`` function now returns standard error codes. See :doc:`/api-reference/network/esp_netif` for more details.
+- The ``esp_netif_deinit()`` function is provided to de-initialize the network stack.
+- You should also replace ``#include "tcpip_adapter.h"`` with ``#include "esp_netif.h"``.
 
 
-Network interface creation
+Network Interface Creation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-TCP/IP Adapter defined these three interfaces statically:
+Previously, the TCP/IP Adapter defined the following network interfaces statically:
 
 - WiFi Station
 - WiFi Access Point
 - Ethernet
 
-Network interface instance shall be explicitly constructed for the :doc:`/api-reference/network/esp_netif` to enable its connection to the TCP/IP stack.
-For example initialization code for WiFi has to explicitly call ``esp_netif_create_default_wifi_sta();`` or ``esp_netif_create_default_wifi_ap();`` after the TCP/IP stack and the event loop have been initialized.
-Please consult an example initialization code for these three interfaces:
+This now changes. Network interface instance should be explicitly constructed, so that the :doc:`/api-reference/network/esp_netif` can connect to the TCP/IP stack. For example, after the TCP/IP stack and the event loop are initialized, the initialization code for WiFi must explicitly call ``esp_netif_create_default_wifi_sta();`` or ``esp_netif_create_default_wifi_ap();``.
+
+Please refer to the example initialization code for these three interfaces:
 
 - WiFi Station: :example_file:`wifi/getting_started/station/main/station_example_main.c`
 - WiFi Access Point: :example_file:`wifi/getting_started/softAP/main/softap_example_main.c`
 - Ethernet: :example_file:`ethernet/basic/main/ethernet_example_main.c`
 
-
-Replacing other tcpip_adapter API
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Other tcpip_adapter API Replacement
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 All the tcpip_adapter functions have their esp-netif counter-part. Please refer to the esp_netif.h grouped into these sections:
 
@@ -117,13 +111,13 @@ All the tcpip_adapter functions have their esp-netif counter-part. Please refer
 *  :component_file:`DNS <esp_netif/include/esp_netif.h#L516>`
 *  :component_file:`IP address <esp_netif/include/esp_netif.h#L568>`
 
-
-Default event handlers
+Default Event Handlers
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, all events shall be handled in the same way.
-Please note that within IP related event handlers, application code usually receives IP addresses in a form of esp-netif specific struct (not the LwIP structs, but binary compatible).
-This is the preferred way of printing the address:
+Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, as all events should be handled in the same way. Please note that for IP-related event handlers, application code usually receives IP addresses in the form of an esp-netif specific struct instead of the LwIP structs. However, both structs are binary compatible.
+
+
+This is the preferred way to print the address:
 
 .. code-block:: c
 
@@ -135,19 +129,18 @@ Instead of
 
            ESP_LOGI(TAG, "got ip:%s\n", ip4addr_ntoa(&event->ip_info.ip));
 
-Since ``ip4addr_ntoa()`` is a LwIP API, the esp-netif provides ``esp_ip4addr_ntoa()`` as a replacement, but the above method is generally preferred.
+Since ``ip4addr_ntoa()`` is a LwIP API, the esp-netif provides ``esp_ip4addr_ntoa()`` as a replacement. However, the above method using ``IP2STR()`` is generally preferred.
 
-
-IP addresses
+IP Addresses
 ^^^^^^^^^^^^
 
-It is preferred to use esp-netif defined IP structures. Please note that the LwIP structs will still work when default compatibility enabled.
-*  :component_file:`esp-netif IP address definitions <esp_netif/include/esp_netif_ip_addr.h#L96>`
+You are advised to use esp-netif defined IP structures. Please note that with default compatibility enabled, the LwIP structs will still work.
 
+*  :component_file:`esp-netif IP address definitions <esp_netif/include/esp_netif_ip_addr.h#L96>`
 
-Next steps
+Next Steps
 ^^^^^^^^^^
 
-Additional step in porting an application to fully benefit from the :doc:`/api-reference/network/esp_netif` is to disable the tcpip_adapter compatibility layer in the component configuration:
-``ESP NETIF Adapter`` -> ``Enable backward compatible tcpip_adapter interface`` and check if the project compiles.
-TCP/IP adapter brings many include dependencies and this step might help in decoupling the application from using specific TCP/IP stack API directly.
+To port an application which may fully benefit from the :doc:`/api-reference/network/esp_netif`, you also need to disable the tcpip_adapter compatibility layer in the component configuration option. Please go to ``ESP NETIF Adapter`` > ``Enable backward compatible tcpip_adapter interface``. After that, check if your project compiles.
+
+The TCP/IP adapter includes many dependencies. Thus, disabling its compatibility might help separate the application from using specific TCP/IP stack API directly.

docs/en/migration-guides/release-5.x/storage.rst

@@ -1,90 +1,91 @@
 Storage
 =======
 
-Breaking changes:
-~~~~~~~~~~~~~~~~~
+FatFs
+-----
 
-f_mkfs() signature change in FATFS v0.14
-----------------------------------------
+FatFs is now updated to v0.14. As a result, the function signature of ``f_mkfs()`` has changed. The new signature is ``FRESULT f_mkfs (const TCHAR* path, const MKFS_PARM* opt, void* work, UINT len);`` which uses ``MKFS_PARM`` struct as a second argument.
 
-New signature is ``FRESULT f_mkfs (const TCHAR* path, const MKFS_PARM* opt, void* work, UINT len);`` which now uses ``MKFS_PARM`` struct as a second argument.
+Partition Table
+---------------
 
-Partition table generation no longer supports misaligned partitions
--------------------------------------------------------------------
+The partition table generator no longer supports misaligned partitions. When generating a partition table, ``esp-idf`` only accepts partitions with offsets that align to 4 KB. This change only affects generating new partition tables. Reading and writing to already existing partitions remains unchanged.
 
-When generating a partiton table, ``esp-idf`` will no longer accept partitions which offset does not align to 4kB. This change only affects generating new partition tables, reading and writing to already existing partitions remains unchanged.
 
-esp_vfs_semihost_register() signature change
---------------------------------------------
+VFS
+---
 
-New signature is ``esp_err_t esp_vfs_semihost_register(const char* base_path);`` Absolute path as a second parameter will no longer in use. Instead, the OpenOCD command ``ESP_SEMIHOST_BASEDIR`` should be used to set the full path on the host.
+The ``esp_vfs_semihost_register()`` function signature is changed as follows:
 
-NVS
----
+- The new signature is ``esp_err_t esp_vfs_semihost_register(const char* base_path);``
+- The ``host_path`` parameter of the old signature no longer exists. Instead, the OpenOCD command ``ESP_SEMIHOST_BASEDIR`` should be used to set the full path on the host.
 
-``nvs_entry_find()``, ``nvs_entry_next()`` and ``nvs_entry_info()`` always return ``esp_err_t`` now instead of ``void`` or ``nvs_iterator_t``. This provides better error reporting when parameters are invalid or something goes wrong internally than returning ``nullptr`` instead of a valid iterator or checking parameters with ``assert``. ``nvs_entry_find()`` and ``nvs_entry_next()`` modify iterators via parameters now instead of returning an iterator.
+Function Signature Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The old programming pattern to iterate over an NVS partition was as follows:
+The following functions now return ``esp_err_t`` instead of ``void`` or ``nvs_iterator_t``. Previously, when parameters were invalid or when something goes wrong internally, these functions would ``assert()`` or return a ``nullptr``. With an ``esp_err_t`` returned, you can get better error reporting.
 
-.. highlight:: c
+- :cpp:func:`nvs_entry_find`
+- :cpp:func:`nvs_entry_next`
+- :cpp:func:`nvs_entry_info`
 
-::
+Because the ``esp_err_t`` return type changes, the usage patterns of ``nvs_entry_find()`` and ``nvs_entry_next()`` become different. Both functions now modify iterators via parameters instead of returning an iterator.
+
+The old programming pattern to iterate over an NVS partition was as follows:
+
+.. code-block:: c
 
     nvs_iterator_t it = nvs_entry_find(<nvs_partition_name>, <namespace>, NVS_TYPE_ANY);
     while (it != NULL) {
             nvs_entry_info_t info;
             nvs_entry_info(it, &info);
             it = nvs_entry_next(it);
-            printf("key '%s', type '%d' \n", info.key, info.type);
+            printf("key '%s', type '%d'", info.key, info.type);
     };
 
 The new programming pattern to iterate over an NVS partition is now:
 
-.. highlight:: c
-
-::
+.. code-block:: c
 
     nvs_iterator_t it = nullptr;
     esp_err_t res = nvs_entry_find(<nvs_partition_name>, <namespace>, NVS_TYPE_ANY, &it);
     while(res == ESP_OK) {
         nvs_entry_info_t info;
         nvs_entry_info(it, &info); // Can omit error check if parameters are guaranteed to be non-NULL
-        printf("key '%s', type '%d' \n", info.key, info.type);
+        printf("key '%s', type '%d'", info.key, info.type);
         res = nvs_entry_next(&it);
     }
     nvs_release_iterator(it);
 
-Signature Changes
+Iterator Validity
 ^^^^^^^^^^^^^^^^^
 
-``nvs_iterator_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t type)`` changes to ``esp_err_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t type, nvs_iterator_t *output_iterator)``. The iterator is returned via the parameter ``output_iterator`` instead of a return value. This allows reporting additional errors, like e.g. memory errors, via the new return value.
-
-``nvs_iterator_t nvs_entry_next(nvs_iterator_t iterator)`` changes to ``esp_err_t nvs_entry_next(nvs_iterator_t *it)``. This allows reporting parameter errors and internal errors, like e.g. flash errors.
+Note that because the function signature changes, if there is a parameter error, you may get an invalid iterator from ``nvs_entry_find()``. Hence, it is important to initialize the iterator to ``NULL`` before using ``nvs_entry_find()``, so that you can avoid complex error checking before calling ``nvs_release_iterator()``. A good example is the programming pattern above.
 
-``void nvs_entry_info(nvs_iterator_t iterator, nvs_entry_info_t *out_info)`` changes to ``esp_err_t nvs_entry_info(const nvs_iterator_t iterator, nvs_entry_info_t *out_info)`` to allow reporting parameter errors.
 
-Iterator Validity
-^^^^^^^^^^^^^^^^^
+Removed SDSPI Deprecated API
+----------------------------
 
-Note that due to the new signatures, it is possible to have an invalid iterator from ``nvs_entry_find()``, if there is a parameter errors. Hence, it is important to initialize the iterator with ``NULL`` before using ``nvs_entry_find()`` to avoid complex error checking before calling ``nvs_release_iterator()``. A good example is the programming pattern above.
+Structure ``sdspi_slot_config_t`` and function ``sdspi_host_init_slot()`` are removed, and replaced by structure ``sdspi_device_config_t`` and function ``sdspi_host_init_device()`` respectively.
 
-Removed SDSPI deprecated API
-----------------------------
+ROM SPI Flash
+^^^^^^^^^^^^^
 
-Removed structure ``sdspi_slot_config_t`` and fuction ``sdspi_host_init_slot``. These were replaced by a structure ``sdspi_device_config_t`` and a fuction ``sdspi_host_init_device`` respectively.
+In versions before v5.0, ROM SPI flash functions were included via ``esp32**/rom/spi_flash.h``. Thus, code written to support different ESP chips might be filled with ROM headers of different targets. Furthermore, not all of the APIs could be used on all ESP chips.
 
-SPI Flash Interface
--------------------
+Now, the common APIs are extracted to ``esp_rom_spiflash.h``. Although it is not a breaking change, you are strongly recommended to only use the functions from this header (i.e., prefixed with ``esp_rom_spiflash`` and included by ``esp_rom_spiflash.h``) for better cross-compatibility between ESP chips.
 
-Version before v5.0, spi flash functions in rom can be included by ``esp32**/rom/spi_flash.h``. However, your code written for different chips may be filled with ROM headers of different versions. At the meantime not all the APIs can be used on all chips.
+To make ROM SPI flash APIs clearer, the following functions are also renamed:
 
-Therefore, the common APIs are extracted to ``esp_rom_spiflash.h``. Although it's not a breaking change, it is strongly recommended to only use the functions with prefix ``esp_rom_spiflash`` included by ``esp_rom_spiflash.h`` for better cross-compatibility.
+- ``esp_rom_spiflash_lock()`` to ``esp_rom_spiflash_set_bp()``
+- ``esp_rom_spiflash_unlock()`` to ``esp_rom_spiflash_clear_bp()``
 
-To make the API clearer, we renamed the function ``esp_rom_spiflash_lock`` to ``esp_rom_spiflash_set_bp``. We renamed ``esp_rom_spiflash_unlock`` to ``esp_rom_spiflash_clear_bp``.
+SPI Flash Driver
+^^^^^^^^^^^^^^^^
 
-ENUM type ``esp_flash_speed_t`` has been deprecated. From now on, you can directly parse the real clock frequency value to the flash initialization structure. For example, if you want the flash frequency is 80M, you can write the code like:
+The ``esp_flash_speed_t`` ``enum`` type is now deprecated. Instead, you may now directly pass the real clock frequency value to the flash configuration structure. The following example demonstrates how to configure a flash frequency of 80MHz:
 
-.. code:: c
+.. code-block:: c
 
     esp_flash_spi_device_config_t dev_cfg = {
         // Other members
@@ -92,29 +93,32 @@ ENUM type ``esp_flash_speed_t`` has been deprecated. From now on, you can direct
         // Other members
     };
 
-Breaking changes in legacy APIs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In order to make spi_flash driver more stable, legacy spi_flash driver is removed on v5.0. Legacy spi_flash driver refers to default spi_flash driver since v3.0 and spi_flash driver with configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` switched on on v4.0 series. The major breaking change is legacy spi_flash driver is not supported on new version anymore. Therefore, the configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` is removed. After that, following functions will no longer exist. But meanwhile, you can use our new APIs instead.
-
-+---------------------------------+-------------------------------+
-|         Removed items           |          Replacement          |
-+=================================+===============================+
-| ``spi_flash_erase_sector()``    | ``esp_flash_erase_region``    |
-+---------------------------------+-------------------------------+
-| ``spi_flash_erase_range()``     | ``esp_flash_erase_region``    |
-+---------------------------------+-------------------------------+
-| ``spi_flash_write``             | ``esp_flash_write``           |
-+---------------------------------+-------------------------------+
-| ``spi_flash_read()``            | ``esp_flash_read``            |
-+---------------------------------+-------------------------------+
-| ``spi_flash_write_encrypted()`` | ``esp_flash_write_encrypted`` |
-+---------------------------------+-------------------------------+
-| ``spi_flash_read_encrypted``    | ``esp_flash_read_encrypted``  |
-+---------------------------------+-------------------------------+
+Legacy SPI Flash Driver
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To make SPI flash drivers more stable, the legacy SPI flash driver is removed from v5.0. The legacy SPI flash driver refers to default spi_flash driver since v3.0, and the SPI flash driver with configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` enabled since v4.0. The major breaking change here is that the legacy spi_flash driver is no longer supported from v5.0. Therefore, the legacy driver APIs and the ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` configuration option are both removed. Please use the new spi_flash driver's APIs instead.
+
+.. list-table::
+    :widths: 50 50
+    :header-rows: 1
+
+    * - Removed items
+      - Replacement
+    * - ``spi_flash_erase_sector()``
+      - ``esp_flash_erase_region()``
+    * - ``spi_flash_erase_range()``
+      - ``esp_flash_erase_region()``
+    * - ``spi_flash_write()``
+      - ``esp_flash_write()``
+    * - ``spi_flash_read()``
+      - ``esp_flash_read()``
+    * - ``spi_flash_write_encrypted()``
+      - ``esp_flash_write_encrypted()``
+    * - ``spi_flash_read_encrypted()``
+      - ``esp_flash_read_encrypted()``
 
 .. note::
 
-    New functions with prefix ``esp_flash`` accept an additional ``esp_flash_t*`` parameter.  You can simply set it to NULL means that the function will operate the main flash(``esp_flash_default_chip``)
+    New functions with prefix ``esp_flash`` accept an additional ``esp_flash_t*`` parameter. You can simply set it to NULL. This will make the function to run the main flash (``esp_flash_default_chip``).
 
-Header ``esp_spi_flash.h`` has been deprecated, system functions are no longer public. To make use of flash memory mapping APIs, you should include ``spi_flash_mmap.h`` instead.
+The ``esp_spi_flash.h`` header is deprecated as system functions are no longer public. To use flash memory mapping APIs, you may include ``spi_flash_mmap.h`` instead.

docs/zh_CN/migration-guides/release-5.x/networking.rst

@@ -1,67 +1,75 @@
-Networking
+网络
 ===========
 
 :link_to_translation:`en:[English]`
 
-Ethernet
-**********
+以太网
+**************
 
 esp_eth_ioctl() API
 -------------------
-:cpp:func:`esp_eth_ioctl` third argument could take `int` (`bool`) number as an input in some cases. However, it was not properly documented and, in addition, the number had to be "unnaturally" type casted to `void *` datatype to prevent compiler warnings as shown in below example:
 
-.. highlight:: c
+此前，:cpp:func:`esp_eth_ioctl` API 存在以下问题：
 
-::
-
-    esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true);
+    - 在某些情况下，第三个参数（数据类型为 ``void /*``）可以接受 ``int``/``bool`` 类型实参（而非指针）作为输入。然而，文档中未描述这些情况。
+    - 为了将 ``int``/``bool`` 类型实参作为第三个参数传递，实参将被强制转换为 ``void *`` 类型，以防出现如下所示的编译器警告。此等转换可能引起 :cpp:func:`esp_eth_ioctl` 函数的滥用。
 
+.. code-block:: c
 
-This could lead to misuse of the :cpp:func:`esp_eth_ioctl`. Therefore, ESP-IDF 5.0 unified usage of :cpp:func:`esp_eth_ioctl`. Its third argument now always acts as pointer to a memory location of specific type from/to where the configuration option is read/stored.
+    esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true);
 
-Usage example to set Ethernet configuration:
+因此，我们统一了 :cpp:func:`esp_eth_ioctl` 的用法。现在，该结构体的第三个参数在传递时必须作为指向特定数据类型的指针，表示 :cpp:func:`esp_eth_ioctl` 读取/存储数据的位置。:cpp:func:`esp_eth_ioctl` 的用法如下列代码所示。
 
-.. highlight:: c
+设置以太网配置的用例如下：
 
-::
+.. code-block:: c
 
     eth_duplex_t new_duplex_mode = ETH_DUPLEX_HALF;
     esp_eth_ioctl(eth_handle, ETH_CMD_S_DUPLEX_MODE, &new_duplex_mode);
 
-Usage example to get Ethernet configuration:
-
-.. highlight:: c
-
-::
+获取以太网配置的用例如下：
 
+.. code-block:: c
+    
     eth_duplex_t duplex_mode;
     esp_eth_ioctl(eth_handle, ETH_CMD_G_DUPLEX_MODE, &duplex_mode);
 
+KSZ8041/81 和 LAN8720 驱动更新
+--------------------------------------------
+
+KSZ8041/81 和 LAN8720 驱动现已更新，以支持相关产品系列中的更多设备（如新一代设备）。上述驱动能够识别特定芯片编号及驱动提供的潜在支持。
+
+更新之后，通用函数将替代特定“芯片编号”函数得以调用：
+
+* 删除 ``esp_eth_phy_new_ksz8041()`` 以及 ``esp_eth_phy_new_ksz8081()``，转而使用 :cpp:func:`esp_eth_phy_new_ksz80xx`
+* 删除 ``esp_eth_phy_new_lan8720()``，转而使用 :cpp:func:`esp_eth_phy_new_lan87xx`
 
-KSZ8041/81 and LAN8720 Driver Update
-------------------------------------
-KSZ8041/81 and LAN8720 Drivers were updated to support more devices (generations) from associated product family. The drivers are able to recognize particular chip number and its potential support by the driver.
 
-As a result, the specific "chip number" functions calls were replaced by generic ones as follows:
+ESP NETIF Glue 时间处理程序
+-----------------------------------
 
-* `esp_eth_phy_new_ksz8041` and `esp_eth_phy_new_ksz8081` were removed, use :cpp:func:`esp_eth_phy_new_ksz80xx` instead
-* `esp_eth_phy_new_lan8720` was removed, use :cpp:func:`esp_eth_phy_new_lan87xx` instead
+``esp_eth_set_default_handlers()`` 和 ``esp_eth_clear_default_handlers()`` 函数现已删除。现在可以自动处理以太网默认 IP 层处理程序的注册。如您在注册以太网/IP 事件处理程序之前已经按照建议完全初始化以太网驱动和网络接口，则无需执行任何操作（除了删除受影响的函数）。否则，在注册用户事件处理程序后，应随即启动以太网驱动。
 
+PHY 地址自动检测
+---------------------------
 
-ESP NETIF Glue Event Handlers
------------------------------
-``esp_eth_set_default_handlers()`` and ``esp_eth_clear_default_handlers()`` functions were removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If users have already followed the recommendation to fully initialize the Ethernet driver and network interface prior to registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Otherwise, users should ensure that they register the user event handlers as the last thing prior to starting the Ethernet driver.
+以太网 PHY 地址自动检测函数 ``esp_eth_detect_phy_addr()`` 已重命名为 :cpp:func:`esp_eth_phy_802_3_detect_phy_addr`，其声明移至 :component_file:`esp_eth/include/esp_eth_phy_802_3.h`。
+
+
+SPI 以太网模块初始化
+--------------------------------------
+
+SPI 以太网模块的初始化过程已经简化。此前，您需要在实例化 SPI 以太网 MAC 之前，使用 :cpp:func:`spi_bus_add_device` 手动分配 SPI 设备。
+
+现在，由于 SPI 设备已在内部分配，您无需再调用 :cpp:func:`spi_bus_add_device`。:cpp:class:`eth_dm9051_config_t`、:cpp:class:`eth_w5500_config_t` 和 :cpp:class:`eth_ksz8851snl_config_t` 配置结构体现已包含 SPI 设备配置成员（例如，可以微调可能依赖 PCB 设计的 SPI 时序）。``ETH_DM9051_DEFAULT_CONFIG``、``ETH_W5500_DEFAULT_CONFIG`` 和 ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` 配置初始化宏也已接受新的参数输入。了解 SPI 以太网模块初始化示例，请查看 :doc:`以太网 API 参考指南<../../api-reference/network/esp_eth>`。
 
-PHY Address Auto-detect
------------------------
-Ethernet PHY address auto-detect function ``esp_eth_detect_phy_addr`` was renamed to :cpp:func:`esp_eth_phy_802_3_detect_phy_addr` and its header declaration was moved to :component_file:`esp_eth/include/esp_eth_phy_802_3.h`.
 
 .. _tcpip-adapter:
 
 TCP/IP 适配器
-*************
+****************
 
-TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。本文档概述了从 tcpip_adapter 移出至其后继者 :doc:`/api-reference/network/esp_netif` 的过程。
+TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。本文档概述了从 tcpip_adapter API 迁移至 :doc:`/api-reference/network/esp_netif` 的过程。
 
 
 更新网络连接代码
@@ -71,45 +79,44 @@ TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。
 网络软件栈初始化
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-只需将 ``tcpip_adapter_init()`` 替换为 ``esp_netif_init()``。请注意，:doc:`/api-reference/network/esp_netif` 初始化 API 可返回标准错误代码，还可以使用 ``esp_netif_deinit()`` 进行去初始化。
-
-此外，还需将 ``#include "tcpip_adapter.h"`` 替换为 ``#include "esp_netif.h"``。
+- 您只需用 ``esp_netif_init()`` 替换 ``tcpip_adapter_init()``，注意 ``esp_netif_init()`` 函数现将返回标准错误代码。了解详细信息，请参考 :doc:`/api-reference/network/esp_netif`。
+- ``esp_netif_deinit()`` 函数用于反初始化网络软件栈。
+- 您还需用 ``#include "esp_netif.h"`` 替换 ``#include "tcpip_adapter.h"``。
 
 
 创建网络接口
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-TCP/IP 适配器静态定义了三个接口：
+更新之前，TCP/IP 适配器静态定义了以下三个接口：
 
 - Wi-Fi Station
 - Wi-Fi AP
 - 以太网
 
-网络接口的设计应严格参考 :doc:`/api-reference/network/esp_netif`，以使其能够连接到 TCP/IP 软件栈。
-例如，在 TCP/IP 软件栈和事件循环初始化完成后，Wi-Fi 的初始化代码必须显示调用 ``esp_netif_create_default_wifi_sta();`` 或 ``esp_netif_create_default_wifi_ap();``。
-请参阅这三个接口的初始化代码示例：
+接口定义现已更新。网络接口的设计应严格参考 :doc:`/api-reference/network/esp_netif`，使其能够连接至 TCP/IP 软件栈。例如，在 TCP/IP 软件栈和事件循环初始化完成后，Wi-Fi 的初始化代码必须显示调用 ``esp_netif_create_default_wifi_sta();`` 或 ``esp_netif_create_default_wifi_ap();``。
 
-- Wi-Fi Station: :example_file:`wifi/getting_started/station/main/station_example_main.c`
-- Wi-Fi AP: :example_file:`wifi/getting_started/softAP/main/softap_example_main.c`
-- 以太网: :example_file:`ethernet/basic/main/ethernet_example_main.c`
+请参考上述三个接口的初始化代码示例：
 
+- Wi-Fi Station：:example_file:`wifi/getting_started/station/main/station_example_main.c`
+- Wi-Fi AP：:example_file:`wifi/getting_started/softAP/main/softap_example_main.c`
+- 以太网：:example_file:`ethernet/basic/main/ethernet_example_main.c`
 
-更换 tcpip_adapter API
+其他 tcpip_adapter API 更换
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-所有 tcpip_adapter 函数都有对应的 esp-netif。请参阅 esp_netif.h 查看更多信息：
+所有 tcpip_adapter 函数都有对应的 esp-netif。请参考以下章节中的 esp_netif.h 部分，了解更多信息：
 
 * :component_file:`Setters/Getters <esp_netif/include/esp_netif.h#L241>`
 * :component_file:`DHCP <esp_netif/include/esp_netif.h#L387>`
 * :component_file:`DNS <esp_netif/include/esp_netif.h#L516>`
 * :component_file:`IP address <esp_netif/include/esp_netif.h#L568>`
 
-
 默认事件处理程序
 ^^^^^^^^^^^^^^^^^^^^^^
 
-事件处理程序已经从 tcpip_adapter 移动到相应的驱动程序代码。从应用程序的角度来看，这不会带来任何影响，所有事件仍以相同的方式处理。
-请注意，在与 IP 相关的事件处理程序中，应用程序代码通常以 esp-netif 结构体的形式接收 IP 地址，该结构体并非 LwIP 结构，但兼容二进制格式。
+事件处理程序已从 tcpip_adapter 移至相应驱动程序代码。从应用程序的角度来看，这一变更不会产生任何影响，所有事件仍将以相同的方式处理。请注意，在与 IP 相关的事件处理程序中，应用程序代码通常以 esp-netif 结构体而非 LwIP 结构体的形式接收 IP 地址。两种结构体均兼容二进制格式。
+
+
 打印地址的首选方式如下所示：
 
 .. code-block:: c
@@ -122,19 +129,18 @@ TCP/IP 适配器静态定义了三个接口：
 
     ESP_LOGI(TAG, "got ip:%s\n", ip4addr_ntoa(&event->ip_info.ip));
 
-由于 ``ip4addr_ntoa()`` 为 LwIP API，因此 esp-netif 还提供了替代函数 ``esp_ip4addr_ntoa()``，但整体而言，仍推荐使用第一种方法。
-
+``ip4addr_ntoa()`` 为 LwIP API，因此 esp-netif 还提供了替代函数 ``esp_ip4addr_ntoa()``，然而总得来说仍推荐使用 ``IP2STR()`` 这一方法。
 
 IP 地址
 ^^^^^^^^^^^^
 
 推荐使用 esp-netif 定义的 IP 结构。请注意，在启用默认兼容性时，LwIP 结构体仍然可以工作。
+
 * :component_file:`esp-netif IP address definitions <esp_netif/include/esp_netif_ip_addr.h#L96>`
 
+后续步骤
+^^^^^^^^^^^^^^
 
-下一步
-^^^^^^^^^^
+为了令移植应用程序可以使用 :doc:`/api-reference/network/esp_netif`，还需在组件配置中禁用 tcpip_adapter 兼容层。请前往 ``ESP NETIF Adapter`` > ``Enable backward compatible tcpip_adapter interface`` 进行设置，并检查项目是否编译成功。
 
-为了令移植应用程序可以使用 :doc:`/api-reference/network/esp_netif`，还需在组件配置中禁用 tcpip_adapter 兼容层。
-方法为：``ESP NETIF Adapter`` -> ``Enable backward compatible tcpip_adapter interface``，并检查工程是否编译成功。
-TCP/IP 适配器涉及大量依赖项，这一步可能有助于将应用程序与使用特定 TCP/IP 软件栈的 API 分离开来。
+TCP/IP 适配器涉及大量依赖项，禁用兼容层可能有助于将应用程序与使用特定 TCP/IP 软件栈的 API 分离开来。

docs/zh_CN/migration-guides/release-5.x/storage.rst

@@ -1 +1,124 @@
-.. include:: ../../../en/migration-guides/release-5.x/storage.rst
+存储
+=======
+
+FatFs
+-----
+
+FatFs 已更新至 v0.14， ``f_mkfs()`` 函数签名也已变更。新签名为 ``FRESULT f_mkfs (const TCHAR* path, const MKFS_PARM* opt, void* work, UINT len);``，使用 ``MKFS_PARM`` 结构体作为第二个实参。
+
+分区表
+---------------
+
+分区表生成器不再支持未对齐的分区。生成分区表时， ``esp-idf`` 将只接受偏移量与 4 KB 对齐的分区。此变更仅影响新生成的分区表，不影响读写现有分区。
+
+
+VFS
+---
+
+``esp_vfs_semihost_register()`` 函数签名有所更改：
+
+- 新签名为 ``esp_err_t esp_vfs_semihost_register(const char* base_path);``
+- 旧签名的 ``host_path`` 参数不再存在，请使用 OpenOCD 命令 ``ESP_SEMIHOST_BASEDIR`` 设置主机上的完整路径。
+
+函数签名更改
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+以下函数现将返回 ``esp_err_t``，而非 ``void`` 或 ``nvs_iterator_t``。此前，当参数无效或内部出现问题时，这些函数将 ``assert()`` 或返回 ``nullptr``。通过返回 ``esp_err_t``，您将获得更加实用的错误报告。
+
+- :cpp:func:`nvs_entry_find`
+- :cpp:func:`nvs_entry_next`
+- :cpp:func:`nvs_entry_info`
+
+由于 ``esp_err_t`` 返回类型的更改， ``nvs_entry_find()`` 和 ``nvs_entry_next()`` 的使用模式也发生了变化。上述函数现均通过参数修改迭代器，而非返回一个迭代器。
+
+迭代 NVS 分区的旧编程模式如下所示：
+
+.. code-block:: c
+
+    nvs_iterator_t it = nvs_entry_find(<nvs_partition_name>, <namespace>, NVS_TYPE_ANY);
+    while (it != NULL) {
+            nvs_entry_info_t info;
+            nvs_entry_info(it, &info);
+            it = nvs_entry_next(it);
+            printf("key '%s', type '%d'", info.key, info.type);
+    };
+
+现在，迭代 NVS 分区的编程模式已更新为：
+
+.. code-block:: c
+
+    nvs_iterator_t it = nullptr;
+    esp_err_t res = nvs_entry_find(<nvs_partition_name>, <namespace>, NVS_TYPE_ANY, &it);
+    while(res == ESP_OK) {
+        nvs_entry_info_t info;
+        nvs_entry_info(it, &info); // Can omit error check if parameters are guaranteed to be non-NULL
+        printf("key '%s', type '%d'", info.key, info.type);
+        res = nvs_entry_next(&it);
+    }
+    nvs_release_iterator(it);
+
+迭代器有效性
+^^^^^^^^^^^^^^^^^
+
+请注意，由于函数签名的改动，如果存在参数错误，则可能从 ``nvs_entry_find()`` 获得无效迭代器。因此，请务必在使用 ``nvs_entry_find()`` 之前将迭代器初始化为 ``NULL``，以免在调用 ``nvs_release_iterator()`` 之前进行复杂的错误检查。上述编程模式便是一个很好的例子。
+
+
+删除 SDSPI 弃用的 API
+-------------------------------------
+
+结构体 ``sdspi_slot_config_t`` 和函数 ``sdspi_host_init_slot()`` 现已删除，并由结构体 ``sdspi_device_config_t`` 和函数 ``sdspi_host_init_device()`` 替代。
+
+ROM SPI flash
+^^^^^^^^^^^^^
+
+在 v5.0 之前的版本中，ROM SPI flash 函数一般通过 ``esp32**/rom/spi_flash.h`` 得以体现。因此，为支持不同 ESP 芯片而编写的代码可能会填充不同目标的 ROM 头文件。此外，并非所有 API 都可以在全部的 ESP 芯片上使用。
+
+现在，常用 API 被提取至 ``esp_rom_spiflash.h``。尽管这不能算作重大变更，我们强烈建议您仅使用此头文件中的函数（即以 ``esp_rom_spiflash`` 为前缀并包含在 ``esp_rom_spiflash.h`` 中），以获得不同 ESP 芯片之间更佳的交叉兼容性。
+
+为了提高 ROM SPI flash API 的可读性，以下函数也被重命名：
+
+- ``esp_rom_spiflash_lock()`` 更名为 ``esp_rom_spiflash_set_bp()``
+- ``esp_rom_spiflash_unlock()`` 更名为 ``esp_rom_spiflash_clear_bp()``
+
+SPI flash 驱动
+^^^^^^^^^^^^^^^^^^^^^^
+
+``esp_flash_speed_t`` ``enum`` 类型现已弃用。现在，您可以直接将实际时钟频率值传递给 flash 配置结构。下为配置 80MHz flash 频率的示例：
+
+.. code-block:: c
+  
+    esp_flash_spi_device_config_t dev_cfg = {
+        // Other members
+        .freq_mhz = 80,
+        // Other members
+    };
+
+旧版 SPI flash 驱动
+^^^^^^^^^^^^^^^^^^^^^^^
+
+为了使 SPI flash 驱动更为稳定，v5.0 已经删除旧版 SPI flash 驱动。旧版 SPI flash 驱动程序是指自 v3.0 以来的默认 SPI flash 驱动程序，以及自 v4.0 以来启用配置选项 ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` 的 SPI flash 驱动。从 v5.0 开始，我们将不再支持旧版 SPI flash 驱动程序。因此，旧版驱动 API 和 ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` 配置选项均被删除，请改用新 SPI flash 驱动的 API。
+
+.. list-table::
+    :widths: 50 50
+    :header-rows: 1
+
+    * - 删除项目
+      - 替代项目
+    * - ``spi_flash_erase_sector()``
+      - ``esp_flash_erase_region()``
+    * - ``spi_flash_erase_range()``
+      - ``esp_flash_erase_region()``
+    * - ``spi_flash_write()``
+      - ``esp_flash_write()``
+    * - ``spi_flash_read()``
+      - ``esp_flash_read()``
+    * - ``spi_flash_write_encrypted()``
+      - ``esp_flash_write_encrypted()``
+    * - ``spi_flash_read_encrypted()``
+      - ``esp_flash_read_encrypted()``
+
+.. note::
+
+    带有前缀 ``esp_flash`` 的新函数接受额外的 ``esp_flash_t*`` 参数。您可以直接将其设置为 NULL，从而使函数运行主 flash (``esp_flash_default_chip``)。
+
+由于系统函数不再是公共函数， ``esp_spi_flash.h`` 头文件已停止使用。若要使用 flash 映射 API，请使用 ``spi_flash_mmap.h``。