docs/restructure_migration_guides

docs/conf_common.py

@@ -34,8 +34,7 @@ BT_DOCS = ['api-guides/blufi.rst',
            'api-reference/bluetooth/esp_blufi.rst',
            'api-reference/bluetooth/esp-ble-mesh.rst',
            'api-reference/bluetooth/index.rst',
-           'api-reference/bluetooth/nimble/index.rst',
-           'migration-guides/bluetooth.rst']
+           'api-reference/bluetooth/nimble/index.rst']
 
 CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst',
                    'api-reference/bluetooth/esp_a2dp.rst',
@@ -47,7 +46,8 @@ CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst',
                    'api-reference/bluetooth/esp_hf_client.rst',
                    'api-reference/bluetooth/esp_hf_ag.rst',
                    'api-reference/bluetooth/esp_spp.rst',
-                   'api-reference/bluetooth/esp_gap_bt.rst']
+                   'api-reference/bluetooth/esp_gap_bt.rst',
+                   'migration-guides/release-5.x/bluetooth-classic.rst']
 
 WIFI_DOCS = ['api-guides/wifi.rst',
              'api-guides/wifi-security.rst',

docs/en/migration-guides/bluetooth.rst

@@ -1,37 +0,0 @@
-Migrate Bluetooth to ESP-IDF 5.0
-================================
-
-.. only:: SOC_CLASSIC_BT_SUPPORTED
-
-    Bluedroid
-    ---------
-
-    The following Bluedroid macros, types, and functions have been renamed:
-
-    - :component_file:`bt/host/bluedroid/api/include/api/esp_gap_ble_api.h`
-
-        - In :cpp:enum:`esp_gap_ble_cb_event_t`
-
-            - ``ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT`` renamed to ``ESP_GAP_BLE_SET_PREFERRED_DEFAULT_PHY_COMPLETE_EVT``
-            - ``ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT`` renamed to ``ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT``
-            - ``ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT`` renamed to ``ESP_GAP_BLE_CHANNEL_SELECT_ALGORITHM_EVT``
-
-        - ``esp_ble_wl_opration_t`` renamed to :cpp:enum:`esp_ble_wl_operation_t`
-        - ``esp_ble_gap_cb_param_t.pkt_data_lenth_cmpl`` renamed to ``pkt_data_length_cmpl``
-        - ``esp_ble_gap_cb_param_t.update_whitelist_cmpl.wl_opration`` renamed to ``wl_operation``
-        - ``esp_ble_gap_set_prefered_default_phy`` renamed to :cpp:func:`esp_ble_gap_set_preferred_default_phy`
-        - ``esp_ble_gap_set_prefered_phy`` renamed to :cpp:func:`esp_ble_gap_set_preferred_phy`
-
-    - :component_file:`bt/host/bluedroid/api/include/api/esp_gatt_defs.h`
-
-        - In :cpp:enum:`esp_gatt_status_t`
-
-            - ``ESP_GATT_ENCRYPED_MITM`` renamed to ``ESP_GATT_ENCRYPTED_MITM``
-            - ``ESP_GATT_ENCRYPED_NO_MITM`` renamed to ``ESP_GATT_ENCRYPTED_NO_MITM``
-
-    - :component_file:`bt/host/bluedroid/api/include/api/esp_hf_defs.h`
-
-        - In :cpp:enum:`esp_hf_cme_err_t`
-
-            - ``ESP_HF_CME_MEMEORY_FULL`` renamed to ``ESP_HF_CME_MEMORY_FULL``
-            - ``ESP_HF_CME_MEMEORY_FAILURE`` renamed to ``ESP_HF_CME_MEMORY_FAILURE``

docs/en/migration-guides/bt.rst

@@ -1,81 +0,0 @@
-Migrate Bluetooth to ESP-IDF 5.0
-================================
-
-Jump to the API Reference
-
-* https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/index.html
-
-
-Espressif BT API Changes
-================================
-
-We changes the HFP API names and parameters that may make the function confused. The parameter change and API name change is listed separately.
-
-Main Change
-------------
-
-    - The prefix of `esp_bt_hf_xxx` is not so clear to implicit `HFP AG functional mode`, so change it into `esp_hf_ag_xxx`.
-
-    - Separate audio connection and service level connection by changing the API name. The setting up of service level connection (SLC) means that the ACL channel of Bluetooth you can send or get AT command.
-
-API Name & Parameter Change
-----------------------------
-
-    - ``esp_bt_hf_init(esp_bd_addr_t remote_addr)`` changes into ``esp_hf_ag_init(void)``.
-
-    - ``esp_bt_hf_deinit(esp_bd_addr_t remote_addr)`` chanegs into ``esp_hf_ag_deinit(void)``
-
-Along with this change, the `bt_bdaddr_t init` and  `bt_bdaddr_t deinit` has been removed from `union btc_arg_t`.
-
-
-Parameter Change Only
------------------------
-
-    - Reserved.
-
-API Name Change Only
------------------------
-
-HFP AG APIs has all been renamed.
-
-    - ``esp_bt_hf_register_callback`` is now changed into ``esp_hf_ag_register_callback``.
-
-    - ``esp_bt_hf_connect`` changes into ``esp_hf_ag_slc_connect``
-    
-    - ``esp_bt_hf_disconnect`` changes into ``esp_hf_ag_slc_disconnect``
-
-    - ``esp_bt_hf_connect_audio`` changes into ``esp_hf_ag_audio_connect``
-
-    - ``esp_bt_hf_disconnect_audio`` changes into ``esp_hf_ag_audio_disconnect``
-
-    - ``esp_bt_hf_vra`` changes into ``esp_hf_ag_vra_control``
-
-    - ``esp_bt_hf_volume_control`` changes into ``esp_hf_ag_volume_control``
-    
-    - ``esp_hf_unat_response`` changes into ``esp_hf_ag_unknown_at_send``
-
-    - ``esp_bt_hf_cmee_response`` changes into ``esp_hf_ag_cmee_send``
-
-    - ``esp_bt_hf_indchange_notification`` changes into ``esp_hf_ag_devices_status_indchange``
-
-    - ``esp_bt_hf_cind_response`` changes into ``esp_hf_ag_cind_response``
-
-    - ``esp_bt_hf_cops_response`` changes into ``esp_hf_ag_cops_response``
-
-    - ``esp_bt_hf_clcc_response`` changes into ``esp_hf_ag_clcc_response``
-
-    - ``esp_bt_hf_cnum_response`` changes into ``esp_hf_ag_cnum_response``
-
-    - ``esp_bt_hf_bsir`` changes into ``esp_hf_ag_bsir``
-
-    - ``esp_bt_hf_answer_call`` changes into ``esp_hf_ag_answer_call``
-
-    - ``esp_bt_hf_reject_call`` changes into ``esp_hf_ag_reject_call``
-
-    - ``esp_bt_hf_out_call`` changes into ``esp_hf_ag_out_call``
-
-    - ``esp_bt_hf_end_call`` changes into ``esp_hf_ag_end_call``
-
-    - ``esp_bt_hf_register_data_callback`` changes into ``esp_hf_ag_register_data_callback``
-
-    - ``esp_hf_outgoing_data_ready`` changes into ``esp_hf_ag_outgoing_data_ready``

docs/en/migration-guides/ethernet.rst

@@ -1,58 +0,0 @@
-Migrate Ethernet Drivers to ESP-IDF 5.0
-=======================================
-
-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
-
-::
-
-    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.
-
-Usage example to set Ethernet configuration:
-
-.. highlight:: 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
-
-::
-
-    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.
-
-As a result, the specific "chip number" functions calls were 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
-
-
-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 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`.
-
-
-SPI-Ethernet Modules Initialization
------------------------------------
-SPI-Ethernet Modules Initialization was simplified. It is not needed to create an SPI device handle by calling :cpp:func:`spi_bus_add_device` prior SPI-Ethernet MAC instance creation since it is done internally now. The configuration structures :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t` and :cpp:class:`eth_ksz8851snl_config_t` members were updated to include SPI device configuration (to be able to fine tune SPI timig which may be dependend on PCB design, for instance). See :doc:`Ethernet <../api-reference/network/esp_eth>` to find SPI-Ethernet Module initialization example.

docs/en/migration-guides/freertos.rst

@@ -1,37 +0,0 @@
-Migrate FreeRTOS to ESP-IDF 5.0
-==================================
-
-Legacy API and Data Types
--------------------------
-
-Previously, the `configENABLE_BACKWARD_COMPATIBILITY` option was set by default, thus allowed pre FreeRTOS v8.0.0 function names and data types to be used. The `configENABLE_BACKWARD_COMPATIBILITY` is now disabled by default, thus legacy FreeRTOS names/types are no longer supportd by default. Users should either:
-
-- Update their code to remove usage of legacy FreeRTOS names/types
-- Enable the :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` to explicitly allow the usage of legacy names/types
-
-Tasks Snapshot
---------------
-
-The header ``task_snapshot.h`` has been removed from ``freertos/task.h``. ESP-IDF developers should include ``"freertos/task_snapshot.h``` in case they need tasks snapshot API.
-
-The function :cpp:func:`vTaskGetSnapshot` now returns ``BaseType_t``. Return value shall be ``pdTRUE`` on success and ``pdFALSE`` otherwise.
-
-FreeRTOS Asserts
-----------------
-Previously FreeRTOS asserts were configured separately from the rest of the system using the `FREERTOS_ASSERT` kconfig option. This option has now been removed and the configuration is now done through `COMPILER_OPTIMIZATION_ASSERTION_LEVEL`.
-
-Port Macro APIs
----------------
-The file ``portmacro_deprecated.h`` which was added to maintain backward compatibility for deprecated APIs is removed. Users are advised to use the alternate functions for the deprecated APIs as listed below:
-
-- ``portENTER_CRITICAL_NESTED()`` is removed. Users should use the ``portSET_INTERRUPT_MASK_FROM_ISR()`` macro instead.
-- ``portEXIT_CRITICAL_NESTED()`` is removed. Users should use the ``portCLEAR_INTERRUPT_MASK_FROM_ISR()`` macro instead.
-- ``vPortCPUInitializeMutex()`` is removed. Users should use the ``spinlock_initialize()`` function instead.
-- ``vPortCPUAcquireMutex()`` is removed. Users should use the ``spinlock_acquire()`` function instead.
-- ``vPortCPUAcquireMutexTimeout()`` is removed. Users should use the ``spinlock_acquire()`` function instead.
-- ``vPortCPUReleaseMutex()`` is removed. Users should use the ``spinlock_release()`` function instead.
-
-
-Placing FreeRTOS Functions in Flash
------------------------------------
-Previously, the :ref:`CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH` would also place the functions from :component`esp_ringbuf` in flash. ESP-Ringbuf function placement are now controlled by its own configs: :ref:`CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH` and :ref:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`.

docs/en/migration-guides/index.rst

@@ -1,22 +1,12 @@
-ESP-IDF 5.0 Migration Guides
-****************************
+Migration Guides
+*****************
+
 :link_to_translation:`zh_CN:[中文]`
 
+ESP-IDF 5.x Migration Guide
+===========================
+
 .. toctree::
     :maxdepth: 1
 
-    build-system
-    windows-env
-    :SOC_BT_SUPPORTED: bluetooth
-    ethernet
-    freertos
-    peripherals
-    protocols
-    provisioning
-    removed-components
-    storage
-    system
-    tools
-    tcpip-adapter
-    gcc
-    bt
+    release-5.x/index

docs/en/migration-guides/release-5.x/bluetooth-classic.rst

@@ -0,0 +1,87 @@
+Bluetooth Classic
+=================
+
+Bluedroid
+---------
+
+    The following Bluedroid macros, types, and functions have been renamed:
+
+    - :component_file:`bt/host/bluedroid/api/include/api/esp_gap_ble_api.h`
+
+        - In :cpp:enum:`esp_gap_ble_cb_event_t`
+
+            - ``ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT`` renamed to ``ESP_GAP_BLE_SET_PREFERRED_DEFAULT_PHY_COMPLETE_EVT``
+            - ``ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT`` renamed to ``ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT``
+            - ``ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT`` renamed to ``ESP_GAP_BLE_CHANNEL_SELECT_ALGORITHM_EVT``
+
+        - ``esp_ble_wl_opration_t`` renamed to :cpp:enum:`esp_ble_wl_operation_t`
+        - ``esp_ble_gap_cb_param_t.pkt_data_lenth_cmpl`` renamed to ``pkt_data_length_cmpl``
+        - ``esp_ble_gap_cb_param_t.update_whitelist_cmpl.wl_opration`` renamed to ``wl_operation``
+        - ``esp_ble_gap_set_prefered_default_phy`` renamed to :cpp:func:`esp_ble_gap_set_preferred_default_phy`
+        - ``esp_ble_gap_set_prefered_phy`` renamed to :cpp:func:`esp_ble_gap_set_preferred_phy`
+
+    - :component_file:`bt/host/bluedroid/api/include/api/esp_gatt_defs.h`
+
+        - In :cpp:enum:`esp_gatt_status_t`
+
+            - ``ESP_GATT_ENCRYPED_MITM`` renamed to ``ESP_GATT_ENCRYPTED_MITM``
+            - ``ESP_GATT_ENCRYPED_NO_MITM`` renamed to ``ESP_GATT_ENCRYPTED_NO_MITM``
+
+    - :component_file:`bt/host/bluedroid/api/include/api/esp_hf_defs.h`
+
+        - In :cpp:enum:`esp_hf_cme_err_t`
+
+            - ``ESP_HF_CME_MEMEORY_FULL`` renamed to ``ESP_HF_CME_MEMORY_FULL``
+            - ``ESP_HF_CME_MEMEORY_FAILURE`` renamed to ``ESP_HF_CME_MEMORY_FAILURE``
+
+
+    - :component_file:`bt/host/bluedroid/api/include/api/esp_hf_ag_api.h`
+
+        - ``esp_bt_hf_init(esp_bd_addr_t remote_addr)`` changes into ``esp_hf_ag_init(void)``.
+
+        - ``esp_bt_hf_deinit(esp_bd_addr_t remote_addr)`` changes into ``esp_hf_ag_deinit(void)``
+
+            Along with this change, the `bt_bdaddr_t init` and  `bt_bdaddr_t deinit` has been removed from `union btc_arg_t`.
+
+        - ``esp_bt_hf_register_callback`` is now changed into ``esp_hf_ag_register_callback``.
+
+        - ``esp_bt_hf_connect`` changes into ``esp_hf_ag_slc_connect``
+        
+        - ``esp_bt_hf_disconnect`` changes into ``esp_hf_ag_slc_disconnect``
+
+        - ``esp_bt_hf_connect_audio`` changes into ``esp_hf_ag_audio_connect``
+
+        - ``esp_bt_hf_disconnect_audio`` changes into ``esp_hf_ag_audio_disconnect``
+
+        - ``esp_bt_hf_vra`` changes into ``esp_hf_ag_vra_control``
+
+        - ``esp_bt_hf_volume_control`` changes into ``esp_hf_ag_volume_control``
+        
+        - ``esp_hf_unat_response`` changes into ``esp_hf_ag_unknown_at_send``
+
+        - ``esp_bt_hf_cmee_response`` changes into ``esp_hf_ag_cmee_send``
+
+        - ``esp_bt_hf_indchange_notification`` changes into ``esp_hf_ag_devices_status_indchange``
+
+        - ``esp_bt_hf_cind_response`` changes into ``esp_hf_ag_cind_response``
+
+        - ``esp_bt_hf_cops_response`` changes into ``esp_hf_ag_cops_response``
+
+        - ``esp_bt_hf_clcc_response`` changes into ``esp_hf_ag_clcc_response``
+
+        - ``esp_bt_hf_cnum_response`` changes into ``esp_hf_ag_cnum_response``
+
+        - ``esp_bt_hf_bsir`` changes into ``esp_hf_ag_bsir``
+
+        - ``esp_bt_hf_answer_call`` changes into ``esp_hf_ag_answer_call``
+
+        - ``esp_bt_hf_reject_call`` changes into ``esp_hf_ag_reject_call``
+
+        - ``esp_bt_hf_out_call`` changes into ``esp_hf_ag_out_call``
+
+        - ``esp_bt_hf_end_call`` changes into ``esp_hf_ag_end_call``
+
+        - ``esp_bt_hf_register_data_callback`` changes into ``esp_hf_ag_register_data_callback``
+
+        - ``esp_hf_outgoing_data_ready`` changes into ``esp_hf_ag_outgoing_data_ready``
+        

docs/en/migration-guides/build-system.rst → docs/en/migration-guides/release-5.x/build-system.rst

@@ -1,5 +1,5 @@
-Migrate Build System to ESP-IDF 5.0
-===================================
+Build System
+============
 
 Migrating from GNU Make build system
 ------------------------------------

docs/en/migration-guides/gcc.rst → docs/en/migration-guides/release-5.x/gcc.rst

@@ -1,6 +1,5 @@
-==========================
-Migrate IDF Code to GCC 11
-==========================
+GCC 
+***
 
 Previous GCC version was 8.4.0
 

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

@@ -0,0 +1,29 @@
+Migration from 4.4 to 5.0
+-------------------------
+
+:link_to_translation:`zh_CN:[中文]`
+
+.. toctree::
+    :maxdepth: 1
+
+    :SOC_CLASSIC_BT_SUPPORTED: bluetooth-classic
+    build-system
+    gcc
+    networking
+    peripherals
+    protocols
+    provisioning
+    removed-components
+    storage
+    system
+    tools
+
+.. Please create a separate file for each minor release, for example:
+
+.. Migration from 5.0 to 5.1
+.. -------------------------
+
+.. toctree::
+..    :maxdepth: 1
+
+..    release-5.1

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

@@ -1,8 +1,65 @@
-TCP/IP Adapter Migration Guide
-==============================
+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:
+
+.. highlight:: 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.
+
+Usage example to set Ethernet configuration:
+
+.. highlight:: 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
+
+::
+
+    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.
+
+As a result, the specific "chip number" functions calls were 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
+
+
+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 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`.
+
+
+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`.
 
 

docs/en/migration-guides/peripherals.rst → docs/en/migration-guides/release-5.x/peripherals.rst

@@ -1,5 +1,5 @@
-Migrate Peripherals to ESP-IDF 5.0
-==================================
+Peripherals
+===========
 
 Peripheral Clock Gating
 -----------------------
@@ -13,52 +13,6 @@ RTC Subsystem Control
 
 RTC control APIs have been moved from ``driver/rtc_cntl.h`` to ``esp_private/rtc_ctrl.h``.
 
-SPI Flash Interface
--------------------
-
-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.
-
-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.
-
-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``.
-
-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:
-
-.. code:: c
-
-    esp_flash_spi_device_config_t dev_cfg = {
-        // Other members
-        .freq_mhz = 80,
-        // 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``  |
-+---------------------------------+-------------------------------+
-
-.. 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``)
-
-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.
-
 ADC
 ---
 
@@ -76,7 +30,7 @@ The previous Kconfig option `RTCIO_SUPPORT_RTC_GPIO_DESC` has been removed, thus
 Timer Group Driver
 ------------------
 
-Timer Group driver has been redesigned into :doc:`GPTimer <../api-reference/peripherals/gptimer>`, which aims to unify and simplify the usage of general purpose timer. Although it's recommended to use the the new driver APIs, the legacy driver is till available in the previous include path ``driver/timer.h``. However, by default, including ``driver/timer.h`` will bring a build warning like `legacy timer group driver is deprecated, please migrate to driver/gptimer.h`. The warning can be suppressed by the Kconfig option :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN`.
+Timer Group driver has been redesigned into :doc:`GPTimer <../../api-reference/peripherals/gptimer>`, which aims to unify and simplify the usage of general purpose timer. Although it's recommended to use the the new driver APIs, the legacy driver is till available in the previous include path ``driver/timer.h``. However, by default, including ``driver/timer.h`` will bring a build warning like `legacy timer group driver is deprecated, please migrate to driver/gptimer.h`. The warning can be suppressed by the Kconfig option :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN`.
 
 The major breaking changes in concept and usage are listed as follows:
 
@@ -164,7 +118,7 @@ LEDC
     Pulse Counter Driver
     --------------------
 
-    Pulse counter driver has been redesigned (see :doc:`PCNT <../api-reference/peripherals/pcnt>`), which aims to unify and simplify the usage of PCNT peripheral. Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/pcnt.h``. However, by default, including ``driver/pcnt.h`` will bring a build warning like `legacy pcnt driver is deprecated, please migrate to use driver/pulse_cnt.h`. The warning can be suppressed by the Kconfig option :ref:`CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN`.
+    Pulse counter driver has been redesigned (see :doc:`PCNT <../../api-reference/peripherals/pcnt>`), which aims to unify and simplify the usage of PCNT peripheral. Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/pcnt.h``. However, by default, including ``driver/pcnt.h`` will bring a build warning like `legacy pcnt driver is deprecated, please migrate to use driver/pulse_cnt.h`. The warning can be suppressed by the Kconfig option :ref:`CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN`.
 
     The major breaking changes in concept and usage are listed as follows:
 
@@ -201,14 +155,14 @@ LEDC
     - Old API header ``temp_sensor.h`` has been redesigned as ``temperature_sensor.h``, it is recommended to use the new driver and the old driver is not allowed to be used at the same time.
     - Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/temp_sensor.h``. However, by default, including ``driver/temp_sensor.h`` will bring a build warning like "legacy temperature sensor driver is deprecated, please migrate to driver/temperature_sensor.h". The warning can be suppressed by enabling the menuconfig option :ref:`CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN`.
     - Configuration contents has been changed. In old version, user need to configure the ``clk_div`` and ``dac_offset``. While in new version, user only need to choose ``tsens_range``
-    - The process of using temperature sensor has been changed. In old version, user can use ``config->start->read_celsius`` to get value. In the new version, user must install the temperature sensor driver firstly, by ``temperature_sensor_install`` and uninstall it when finished. For more information, you can refer to :doc:`Temperature Sensor <../api-reference/peripherals/temp_sensor>` .
+    - The process of using temperature sensor has been changed. In old version, user can use ``config->start->read_celsius`` to get value. In the new version, user must install the temperature sensor driver firstly, by ``temperature_sensor_install`` and uninstall it when finished. For more information, you can refer to :doc:`Temperature Sensor <../../api-reference/peripherals/temp_sensor>` .
 
 .. only:: SOC_RMT_SUPPORTED
 
     RMT Driver
     ----------
 
-    RMT driver has been redesigned (see :doc:`RMT transceiver <../api-reference/peripherals/rmt>`), which aims to unify and extend the usage of RMT peripheral. Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/rmt.h``. However, by default, including ``driver/rmt.h`` will bring a build warning like `The legacy RMT driver is deprecated, please use driver/rmt_tx.h and/or driver/rmt_rx.h`. The warning can be suppressed by the Kconfig option :ref:`CONFIG_RMT_SUPPRESS_DEPRECATE_WARN`.
+    RMT driver has been redesigned (see :doc:`RMT transceiver <../../api-reference/peripherals/rmt>`), which aims to unify and extend the usage of RMT peripheral. Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/rmt.h``. However, by default, including ``driver/rmt.h`` will bring a build warning like `The legacy RMT driver is deprecated, please use driver/rmt_tx.h and/or driver/rmt_rx.h`. The warning can be suppressed by the Kconfig option :ref:`CONFIG_RMT_SUPPRESS_DEPRECATE_WARN`.
 
     The major breaking changes in concept and usage are listed as follows:
 
@@ -298,7 +252,7 @@ LCD
 
     Shortcomings are exposed when supporting all the new features of ESP32-C3 & ESP32-S3 by the old I2S driver, so it is re-designed to make it more compatible and flexible to all the communication modes. New APIs are available by including corresponding mode header files {I2S_DRIVER_HEADERS}. Meanwhile, the old APIs in :component_file:`driver/deprecated/driver/i2s.h` are still supported for backward compatibility. But there will be warnings if you keep using the old APIs in your project, these warnings can be suppressed by the Kconfig option :ref:`CONFIG_I2S_SUPPRESS_DEPRECATE_WARN`. Here is the general overview of the current I2S files:
 
-    .. figure:: ../../_static/diagrams/i2s/i2s_file_structure.png
+    .. figure:: ../../../_static/diagrams/i2s/i2s_file_structure.png
         :align: center
         :alt: I2S File Structure
 

docs/en/migration-guides/protocols.rst → docs/en/migration-guides/release-5.x/protocols.rst

@@ -1,5 +1,5 @@
-Migration of Protocol Components to ESP-IDF 5.0
-===============================================
+Protocols
+=========
 
 .. _migration_guide_mbedtls:
 

docs/en/migration-guides/provisioning.rst → docs/en/migration-guides/release-5.x/provisioning.rst

@@ -1,5 +1,5 @@
-Migrate Provisioning to ESP-IDF 5.0
-===================================
+Provisioning
+============
 
 Protocomm
 ---------

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

@@ -1,5 +1,5 @@
-Migrate Storage to ESP-IDF 5.0
-==================================
+Storage
+=======
 
 Breaking changes:
 ~~~~~~~~~~~~~~~~~
@@ -73,3 +73,48 @@ Removed SDSPI deprecated API
 
 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.
 
+SPI Flash Interface
+-------------------
+
+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.
+
+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.
+
+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``.
+
+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:
+
+.. code:: c
+
+    esp_flash_spi_device_config_t dev_cfg = {
+        // Other members
+        .freq_mhz = 80,
+        // 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``  |
++---------------------------------+-------------------------------+
+
+.. 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``)
+
+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.

docs/en/migration-guides/system.rst → docs/en/migration-guides/release-5.x/system.rst

@@ -1,5 +1,5 @@
-Migrate System to ESP-IDF 5.0
-==================================
+System
+======
 
 Inter-Processor Call
 -----------------------
@@ -38,7 +38,7 @@ The header ``trax.h`` has been made private. ESP-IDF developers should include `
 
 ROM
 ---
-Deprecated ROM related header files from `components/esp32/rom/` (old include path: `rom/*.h`) have been deleted. Please update to use the new target-specific path from `components/esp_rom/include/{IDF_TARGET_NAME}/` (new include path: `{IDF_TARGET_NAME}/rom/*.h`).
+Deprecated ROM related header files from ``components/esp32/rom/`` (old include path: ``rom/*.h``) have been deleted. Please update to use the new target-specific path from ``components/esp_rom/include/{IDF_TARGET_NAME}/`` (new include path: ``{IDF_TARGET_NAME}/rom/*.h``).
 
 ESP HW Support
 --------------
@@ -63,7 +63,7 @@ The parameter type of function ``esp_secure_boot_read_key_digests()`` changed fr
 ESP Common
 ----------
 
-- `EXT_RAM_ATTR` is deprecated. Use this new macro `EXT_RAM_BSS_ATTR` to put .bss on PSRAM.
+- ``EXT_RAM_ATTR`` is deprecated. Use this new macro ``EXT_RAM_BSS_ATTR`` to put .bss on PSRAM.
 
 ESP System
 ----------
@@ -76,12 +76,12 @@ SOC dependency
 
 - Public API headers who are listed in the Doxyfiles won't expose unstable and unnecessary soc header files like ``soc/soc.h``, ``soc/rtc.h``. That means, the user has to explicitly include them in their code if these "missing" header files are still wanted.
 - Kconfig option ``LEGACY_INCLUDE_COMMON_HEADERS`` is also removed.
-- The header file ``soc/soc_memory_types.h`` has been deprecated. Users should use the ``esp_memory_utils.h`` instead. Including `soc/soc_memory_types.h` will bring a build warning like `soc_memory_types.h is deprecated, please migrate to esp_memory_utils.h`
+- The header file ``soc/soc_memory_types.h`` has been deprecated. Users should use the ``esp_memory_utils.h`` instead. Including ``soc/soc_memory_types.h`` will bring a build warning like ``soc_memory_types.h is deprecated, please migrate to esp_memory_utils.h``
 
 APP Trace
 ---------
 
-One of the timestamp sources has changed from the legacy timer group driver to the new :doc:`GPTimer <../api-reference/peripherals/gptimer>`. Kconfig choices like ``APPTRACE_SV_TS_SOURCE_TIMER00`` has been changed to ``APPTRACE_SV_TS_SOURCE_GPTIMER``. User doesn't need to choose the group and timer ID any more.
+One of the timestamp sources has changed from the legacy timer group driver to the new :doc:`GPTimer <../../api-reference/peripherals/gptimer>`. Kconfig choices like ``APPTRACE_SV_TS_SOURCE_TIMER00`` has been changed to ``APPTRACE_SV_TS_SOURCE_GPTIMER``. User doesn't need to choose the group and timer ID any more.
 
 ESP Timer
 ---------
@@ -109,3 +109,39 @@ Efuse
 -----
 
 - Added eFuse wafer revisions: major and minor. The `esp_efuse_get_chip_ver()` API is not compatible with these changes this is why it was removed. Please use instead of it the following APIs: `efuse_hal_get_major_chip_version()`, `efuse_hal_get_minor_chip_version()` or `efuse_hal_chip_revision()`.
+
+FreeRTOS
+--------
+
+Legacy API and Data Types
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Previously, the ``configENABLE_BACKWARD_COMPATIBILITY`` option was set by default, thus allowed pre FreeRTOS v8.0.0 function names and data types to be used. The ``configENABLE_BACKWARD_COMPATIBILITY`` is now disabled by default, thus legacy FreeRTOS names/types are no longer supportd by default. Users should either:
+
+- Update their code to remove usage of legacy FreeRTOS names/types
+- Enable the :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` to explicitly allow the usage of legacy names/types
+
+Tasks Snapshot
+^^^^^^^^^^^^^^
+
+The header ``task_snapshot.h`` has been removed from ``freertos/task.h``. ESP-IDF developers should include ``freertos/task_snapshot.h`` in case they need tasks snapshot API.
+
+The function :cpp:func:`vTaskGetSnapshot` now returns ``BaseType_t``. Return value shall be ``pdTRUE`` on success and ``pdFALSE`` otherwise.
+
+FreeRTOS Asserts
+^^^^^^^^^^^^^^^^
+
+Previously FreeRTOS asserts were configured separately from the rest of the system using the ``FREERTOS_ASSERT`` kconfig option. This option has now been removed and the configuration is now done through ``COMPILER_OPTIMIZATION_ASSERTION_LEVEL``.
+
+Port Macro APIs
+^^^^^^^^^^^^^^^
+
+The file ``portmacro_deprecated.h`` which was added to maintain backward compatibility for deprecated APIs is removed. Users are advised to use the alternate functions for the deprecated APIs as listed below:
+
+- ``portENTER_CRITICAL_NESTED()`` is removed. Users should use the ``portSET_INTERRUPT_MASK_FROM_ISR()`` macro instead.
+- ``portEXIT_CRITICAL_NESTED()`` is removed. Users should use the ``portCLEAR_INTERRUPT_MASK_FROM_ISR()`` macro instead.
+- ``vPortCPUInitializeMutex()`` is removed. Users should use the ``spinlock_initialize()`` function instead.
+- ``vPortCPUAcquireMutex()`` is removed. Users should use the ``spinlock_acquire()`` function instead.
+- ``vPortCPUAcquireMutexTimeout()`` is removed. Users should use the ``spinlock_acquire()`` function instead.
+- ``vPortCPUReleaseMutex()`` is removed. Users should use the ``spinlock_release()`` function instead.
+

docs/en/migration-guides/tools.rst → docs/en/migration-guides/release-5.x/tools.rst

@@ -1,5 +1,7 @@
-Migrate Tools to ESP-IDF v5.0
-=============================
+Tools
+=====
+
+:link_to_translation:`zh_CN:[中文]`
 
 IDF Monitor
 -----------
@@ -45,3 +47,8 @@ Esptool
 -------
 
 The CONFIG_ESPTOOLPY_FLASHSIZE_DETECT option has been renamed to :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` and has been disabled by default. New and existing projects migrated to ESP-IDF v5.0 will have to set :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`. If this is not possible due to an unknown flash size at build time, then :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` can be enabled. However, once enabled, to keep the digest valid, a SHA256 digest will no longer be appended to the image when updating the binary header with the flash size during flashing.
+
+Windows Environment
+--------------------
+
+The Msys/Mingw-based Windows environment support got deprecated in ESP-IDF v4.0 and was entirely removed in v5.0. Please use :ref:`get-started-windows-tools-installer` to set up a compatible environment. The options include Windows Command Line, Power Shell and the graphical user interface based on Eclipse IDE. In addition, a VS Code-based environment can be set up with the supported plugin: https://github.com/espressif/vscode-esp-idf-extension.

docs/en/migration-guides/windows-env.rst

@@ -1,4 +0,0 @@
-Migrate Windows Environment to ESP-IDF v5.0
-===========================================
-
-The MSYS/MinGW-based Windows environment support has been deprecated since ESP-IDF v4.0 and was entirely removed in v5.0. Please use :ref:`get-started-windows-tools-installer` to set up a compatible Windows environment. The options include Windows Command Line, Power Shell and the graphical user interface based on Eclipse IDE. In addition, a VS Code-based environment can be set up with the `supported plugin <https://github.com/espressif/vscode-esp-idf-extension>`.

docs/zh_CN/migration-guides/bluetooth.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/bluetooth.rst

docs/zh_CN/migration-guides/bt.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/bt.rst

docs/zh_CN/migration-guides/build-system.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/build-system.rst

docs/zh_CN/migration-guides/ethernet.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/ethernet.rst

docs/zh_CN/migration-guides/freertos.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/freertos.rst

docs/zh_CN/migration-guides/gcc.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/gcc.rst

docs/zh_CN/migration-guides/index.rst

@@ -1,22 +1,12 @@
-ESP-IDF 5.0 迁移指南
-********************
+迁移指南
+********
+
 :link_to_translation:`en:[English]`
 
+迁移到 ESP-IDF 5.x
+-------------------
+
 .. toctree::
     :maxdepth: 1
 
-    build-system
-    windows-env
-    :SOC_BT_SUPPORTED: bluetooth
-    ethernet
-    freertos
-    peripherals
-    protocols
-    provisioning
-    removed-components
-    storage
-    system
-    tools
-    tcpip-adapter
-    gcc
-    bt
+    release-5.x/index

docs/zh_CN/migration-guides/peripherals.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/peripherals.rst

docs/zh_CN/migration-guides/protocols.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/protocols.rst

docs/zh_CN/migration-guides/provisioning.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/provisioning.rst

docs/zh_CN/migration-guides/release-5.x/bluetooth-classic.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/bluetooth-classic.rst

docs/zh_CN/migration-guides/release-5.x/build-system.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/build-system.rst

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

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/gcc.rst

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

@@ -0,0 +1,29 @@
+从 4.4 迁移到 5.0
+-----------------
+
+:link_to_translation:`en:[English]`
+
+.. toctree::
+    :maxdepth: 1
+
+    :SOC_CLASSIC_BT_SUPPORTED: bluetooth-classic
+    build-system
+    gcc
+    networking
+    peripherals
+    protocols
+    provisioning
+    removed-components
+    storage
+    system
+    tools
+
+.. Please create a separate file for each minor release, for example:
+
+.. 从 5.0 迁移到 5.1
+.. -----------------
+
+.. toctree::
+..    :maxdepth: 1
+
+..    release-5.1

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

@@ -1,7 +1,64 @@
-TCP/IP 适配器迁移指南
-==============================
+Networking
+===========
 
-:link_to_translation:`en:[英文]`
+: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
+
+::
+
+    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.
+
+Usage example to set Ethernet configuration:
+
+.. highlight:: 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
+
+::
+
+    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.
+
+As a result, the specific "chip number" functions calls were 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
+
+
+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 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`.
+
+
+TCP/IP 适配器
+*************
 
 TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。本文档概述了从 tcpip_adapter 移出至其后继者 :doc:`/api-reference/network/esp_netif` 的过程。
 

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

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/peripherals.rst

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

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/protocols.rst

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

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/provisioning.rst

docs/zh_CN/migration-guides/release-5.x/removed-components.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/removed-components.rst

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

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/storage.rst

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

@@ -0,0 +1 @@
+.. include:: ../../../en/migration-guides/release-5.x/system.rst

docs/zh_CN/migration-guides/tools.rst → docs/zh_CN/migration-guides/release-5.x/tools.rst

@@ -1,5 +1,7 @@
-迁移工具至 ESP-IDF v5.0
-============================
+工具
+====
+
+:link_to_translation:`en:[English]`
 
 IDF 监视器
 -----------
@@ -45,3 +47,8 @@ Esptool
 -------
 
 CONFIG_ESPTOOLPY_FLASHSIZE_DETECT 选项已重命名为 :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE`，且默认禁用。迁移到 ESP-IDF v5.0 的新项目和现有项目必须设置 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`。若因编译时 flash 大小未知而无法设置，可启用 :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE`。但需注意的是，启用该项后，为在烧录期间使用 flash 大小更新二进制头时不会导致摘要无效，映像后将不再附加 SHA256 摘要。
+
+Windows 环境
+-------------
+
+基于 MSYS/MinGW 的 Windows 环境支持已在 ESP-IDF v4.0 中弃用，v5.0 则完全移除了该项服务。请使用 :ref:`get-started-windows-tools-installer` 设置 Windows 兼容环境。目前支持 Windows 命令行、Power Shell 和基于 Eclipse IDE 的图形用户界面等选项。此外，还可以使用 `支持的插件 <https://github.com/espressif/vscode-esp-idf-extension>`，设置基于 VSCode 的环境。

docs/zh_CN/migration-guides/removed-components.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/removed-components.rst

docs/zh_CN/migration-guides/storage.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/storage.rst

docs/zh_CN/migration-guides/system.rst

@@ -1 +0,0 @@
-.. include:: ../../en/migration-guides/system.rst

docs/zh_CN/migration-guides/windows-env.rst

@@ -1,4 +0,0 @@
-迁移 Windows 环境至 ESP-IDF v5.0
-==========================================
-
-基于 MSYS/MinGW 的 Windows 环境支持已在 ESP-IDF v4.0 中弃用，v5.0 则完全移除了该项服务。请使用 :ref:`get-started-windows-tools-installer` 设置 Windows 兼容环境。目前支持 Windows 命令行、Power Shell 和基于 Eclipse IDE 的图形用户界面等选项。此外，还可以使用 `支持的插件 <https://github.com/espressif/vscode-esp-idf-extension>`，设置基于 VSCode 的环境。