From 4526a5abf524d41d72769dfd3a79ca17ad883f4f Mon Sep 17 00:00:00 2001 From: Wang Ning Date: Thu, 7 Jul 2022 16:48:04 +0800 Subject: [PATCH] docs/restructure_migration_guides --- docs/conf_common.py | 6 +- docs/en/migration-guides/bluetooth.rst | 37 -------- docs/en/migration-guides/bt.rst | 81 ----------------- docs/en/migration-guides/ethernet.rst | 58 ------------- docs/en/migration-guides/freertos.rst | 37 -------- docs/en/migration-guides/index.rst | 24 ++--- .../release-5.x/bluetooth-classic.rst | 87 +++++++++++++++++++ .../{ => release-5.x}/build-system.rst | 4 +- .../{ => release-5.x}/gcc.rst | 5 +- .../en/migration-guides/release-5.x/index.rst | 29 +++++++ .../networking.rst} | 61 ++++++++++++- .../{ => release-5.x}/peripherals.rst | 60 ++----------- .../{ => release-5.x}/protocols.rst | 4 +- .../{ => release-5.x}/provisioning.rst | 4 +- .../{ => release-5.x}/removed-components.rst | 0 .../{ => release-5.x}/storage.rst | 49 ++++++++++- .../{ => release-5.x}/system.rst | 48 ++++++++-- .../{ => release-5.x}/tools.rst | 11 ++- docs/en/migration-guides/windows-env.rst | 4 - docs/zh_CN/migration-guides/bluetooth.rst | 1 - docs/zh_CN/migration-guides/bt.rst | 1 - docs/zh_CN/migration-guides/build-system.rst | 1 - docs/zh_CN/migration-guides/ethernet.rst | 1 - docs/zh_CN/migration-guides/freertos.rst | 1 - docs/zh_CN/migration-guides/gcc.rst | 1 - docs/zh_CN/migration-guides/index.rst | 24 ++--- docs/zh_CN/migration-guides/peripherals.rst | 1 - docs/zh_CN/migration-guides/protocols.rst | 1 - docs/zh_CN/migration-guides/provisioning.rst | 1 - .../release-5.x/bluetooth-classic.rst | 1 + .../release-5.x/build-system.rst | 1 + .../migration-guides/release-5.x/gcc.rst | 1 + .../migration-guides/release-5.x/index.rst | 29 +++++++ .../networking.rst} | 63 +++++++++++++- .../release-5.x/peripherals.rst | 1 + .../release-5.x/protocols.rst | 1 + .../release-5.x/provisioning.rst | 1 + .../release-5.x/removed-components.rst | 1 + .../migration-guides/release-5.x/storage.rst | 1 + .../migration-guides/release-5.x/system.rst | 1 + .../{ => release-5.x}/tools.rst | 11 ++- .../migration-guides/removed-components.rst | 1 - docs/zh_CN/migration-guides/storage.rst | 1 - docs/zh_CN/migration-guides/system.rst | 1 - docs/zh_CN/migration-guides/windows-env.rst | 4 - 45 files changed, 412 insertions(+), 349 deletions(-) delete mode 100644 docs/en/migration-guides/bluetooth.rst delete mode 100644 docs/en/migration-guides/bt.rst delete mode 100644 docs/en/migration-guides/ethernet.rst delete mode 100644 docs/en/migration-guides/freertos.rst create mode 100644 docs/en/migration-guides/release-5.x/bluetooth-classic.rst rename docs/en/migration-guides/{ => release-5.x}/build-system.rst (98%) rename docs/en/migration-guides/{ => release-5.x}/gcc.rst (98%) create mode 100644 docs/en/migration-guides/release-5.x/index.rst rename docs/en/migration-guides/{tcpip-adapter.rst => release-5.x/networking.rst} (57%) rename docs/en/migration-guides/{ => release-5.x}/peripherals.rst (86%) rename docs/en/migration-guides/{ => release-5.x}/protocols.rst (98%) rename docs/en/migration-guides/{ => release-5.x}/provisioning.rst (94%) rename docs/en/migration-guides/{ => release-5.x}/removed-components.rst (100%) rename docs/en/migration-guides/{ => release-5.x}/storage.rst (55%) rename docs/en/migration-guides/{ => release-5.x}/system.rst (67%) rename docs/en/migration-guides/{ => release-5.x}/tools.rst (79%) delete mode 100644 docs/en/migration-guides/windows-env.rst delete mode 100644 docs/zh_CN/migration-guides/bluetooth.rst delete mode 100644 docs/zh_CN/migration-guides/bt.rst delete mode 100644 docs/zh_CN/migration-guides/build-system.rst delete mode 100644 docs/zh_CN/migration-guides/ethernet.rst delete mode 100644 docs/zh_CN/migration-guides/freertos.rst delete mode 100644 docs/zh_CN/migration-guides/gcc.rst delete mode 100644 docs/zh_CN/migration-guides/peripherals.rst delete mode 100644 docs/zh_CN/migration-guides/protocols.rst delete mode 100644 docs/zh_CN/migration-guides/provisioning.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/bluetooth-classic.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/build-system.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/gcc.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/index.rst rename docs/zh_CN/migration-guides/{tcpip-adapter.rst => release-5.x/networking.rst} (55%) create mode 100644 docs/zh_CN/migration-guides/release-5.x/peripherals.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/protocols.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/provisioning.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/removed-components.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/storage.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/system.rst rename docs/zh_CN/migration-guides/{ => release-5.x}/tools.rst (78%) delete mode 100644 docs/zh_CN/migration-guides/removed-components.rst delete mode 100644 docs/zh_CN/migration-guides/storage.rst delete mode 100644 docs/zh_CN/migration-guides/system.rst delete mode 100644 docs/zh_CN/migration-guides/windows-env.rst diff --git a/docs/conf_common.py b/docs/conf_common.py index 70cf3af0c6..fc0c35ad3b 100644 --- a/docs/conf_common.py +++ b/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', diff --git a/docs/en/migration-guides/bluetooth.rst b/docs/en/migration-guides/bluetooth.rst deleted file mode 100644 index 87f34ee998..0000000000 --- a/docs/en/migration-guides/bluetooth.rst +++ /dev/null @@ -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`` \ No newline at end of file diff --git a/docs/en/migration-guides/bt.rst b/docs/en/migration-guides/bt.rst deleted file mode 100644 index 561cee4451..0000000000 --- a/docs/en/migration-guides/bt.rst +++ /dev/null @@ -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`` \ No newline at end of file diff --git a/docs/en/migration-guides/ethernet.rst b/docs/en/migration-guides/ethernet.rst deleted file mode 100644 index 4e56339d38..0000000000 --- a/docs/en/migration-guides/ethernet.rst +++ /dev/null @@ -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. diff --git a/docs/en/migration-guides/freertos.rst b/docs/en/migration-guides/freertos.rst deleted file mode 100644 index 61d5d9b090..0000000000 --- a/docs/en/migration-guides/freertos.rst +++ /dev/null @@ -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`. diff --git a/docs/en/migration-guides/index.rst b/docs/en/migration-guides/index.rst index 49c0c76a83..7a657490b0 100644 --- a/docs/en/migration-guides/index.rst +++ b/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 diff --git a/docs/en/migration-guides/release-5.x/bluetooth-classic.rst b/docs/en/migration-guides/release-5.x/bluetooth-classic.rst new file mode 100644 index 0000000000..3fb7824ea6 --- /dev/null +++ b/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`` + \ No newline at end of file diff --git a/docs/en/migration-guides/build-system.rst b/docs/en/migration-guides/release-5.x/build-system.rst similarity index 98% rename from docs/en/migration-guides/build-system.rst rename to docs/en/migration-guides/release-5.x/build-system.rst index 933d1fd4fd..d30e801969 100644 --- a/docs/en/migration-guides/build-system.rst +++ b/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 ------------------------------------ diff --git a/docs/en/migration-guides/gcc.rst b/docs/en/migration-guides/release-5.x/gcc.rst similarity index 98% rename from docs/en/migration-guides/gcc.rst rename to docs/en/migration-guides/release-5.x/gcc.rst index 559dd4d2df..1057ee03af 100644 --- a/docs/en/migration-guides/gcc.rst +++ b/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 diff --git a/docs/en/migration-guides/release-5.x/index.rst b/docs/en/migration-guides/release-5.x/index.rst new file mode 100644 index 0000000000..c9cc97d89e --- /dev/null +++ b/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 diff --git a/docs/en/migration-guides/tcpip-adapter.rst b/docs/en/migration-guides/release-5.x/networking.rst similarity index 57% rename from docs/en/migration-guides/tcpip-adapter.rst rename to docs/en/migration-guides/release-5.x/networking.rst index 8964ed3741..ff9becb18a 100644 --- a/docs/en/migration-guides/tcpip-adapter.rst +++ b/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`. diff --git a/docs/en/migration-guides/peripherals.rst b/docs/en/migration-guides/release-5.x/peripherals.rst similarity index 86% rename from docs/en/migration-guides/peripherals.rst rename to docs/en/migration-guides/release-5.x/peripherals.rst index 564c5a6e41..05d8d296bd 100644 --- a/docs/en/migration-guides/peripherals.rst +++ b/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 diff --git a/docs/en/migration-guides/protocols.rst b/docs/en/migration-guides/release-5.x/protocols.rst similarity index 98% rename from docs/en/migration-guides/protocols.rst rename to docs/en/migration-guides/release-5.x/protocols.rst index e86ecae61f..b21953e686 100644 --- a/docs/en/migration-guides/protocols.rst +++ b/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: diff --git a/docs/en/migration-guides/provisioning.rst b/docs/en/migration-guides/release-5.x/provisioning.rst similarity index 94% rename from docs/en/migration-guides/provisioning.rst rename to docs/en/migration-guides/release-5.x/provisioning.rst index ff318526d6..3fdc7d1e60 100644 --- a/docs/en/migration-guides/provisioning.rst +++ b/docs/en/migration-guides/release-5.x/provisioning.rst @@ -1,5 +1,5 @@ -Migrate Provisioning to ESP-IDF 5.0 -=================================== +Provisioning +============ Protocomm --------- diff --git a/docs/en/migration-guides/removed-components.rst b/docs/en/migration-guides/release-5.x/removed-components.rst similarity index 100% rename from docs/en/migration-guides/removed-components.rst rename to docs/en/migration-guides/release-5.x/removed-components.rst diff --git a/docs/en/migration-guides/storage.rst b/docs/en/migration-guides/release-5.x/storage.rst similarity index 55% rename from docs/en/migration-guides/storage.rst rename to docs/en/migration-guides/release-5.x/storage.rst index c571ea8875..6af864b457 100644 --- a/docs/en/migration-guides/storage.rst +++ b/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. diff --git a/docs/en/migration-guides/system.rst b/docs/en/migration-guides/release-5.x/system.rst similarity index 67% rename from docs/en/migration-guides/system.rst rename to docs/en/migration-guides/release-5.x/system.rst index 01a0171345..164a7cea0a 100644 --- a/docs/en/migration-guides/system.rst +++ b/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. + diff --git a/docs/en/migration-guides/tools.rst b/docs/en/migration-guides/release-5.x/tools.rst similarity index 79% rename from docs/en/migration-guides/tools.rst rename to docs/en/migration-guides/release-5.x/tools.rst index df231b7797..063e3dfe81 100644 --- a/docs/en/migration-guides/tools.rst +++ b/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. diff --git a/docs/en/migration-guides/windows-env.rst b/docs/en/migration-guides/windows-env.rst deleted file mode 100644 index a8645c7cad..0000000000 --- a/docs/en/migration-guides/windows-env.rst +++ /dev/null @@ -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 `. diff --git a/docs/zh_CN/migration-guides/bluetooth.rst b/docs/zh_CN/migration-guides/bluetooth.rst deleted file mode 100644 index 6a892d9a7a..0000000000 --- a/docs/zh_CN/migration-guides/bluetooth.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/bluetooth.rst diff --git a/docs/zh_CN/migration-guides/bt.rst b/docs/zh_CN/migration-guides/bt.rst deleted file mode 100644 index b46812b976..0000000000 --- a/docs/zh_CN/migration-guides/bt.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/bt.rst diff --git a/docs/zh_CN/migration-guides/build-system.rst b/docs/zh_CN/migration-guides/build-system.rst deleted file mode 100644 index 2662f1bcdb..0000000000 --- a/docs/zh_CN/migration-guides/build-system.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/build-system.rst diff --git a/docs/zh_CN/migration-guides/ethernet.rst b/docs/zh_CN/migration-guides/ethernet.rst deleted file mode 100644 index 75f8623dbe..0000000000 --- a/docs/zh_CN/migration-guides/ethernet.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/ethernet.rst diff --git a/docs/zh_CN/migration-guides/freertos.rst b/docs/zh_CN/migration-guides/freertos.rst deleted file mode 100644 index 8c6fe659a4..0000000000 --- a/docs/zh_CN/migration-guides/freertos.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/freertos.rst diff --git a/docs/zh_CN/migration-guides/gcc.rst b/docs/zh_CN/migration-guides/gcc.rst deleted file mode 100644 index 351d864870..0000000000 --- a/docs/zh_CN/migration-guides/gcc.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/gcc.rst diff --git a/docs/zh_CN/migration-guides/index.rst b/docs/zh_CN/migration-guides/index.rst index 6c1cef4643..9ce57cfea9 100644 --- a/docs/zh_CN/migration-guides/index.rst +++ b/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 diff --git a/docs/zh_CN/migration-guides/peripherals.rst b/docs/zh_CN/migration-guides/peripherals.rst deleted file mode 100644 index 986d95906d..0000000000 --- a/docs/zh_CN/migration-guides/peripherals.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/peripherals.rst diff --git a/docs/zh_CN/migration-guides/protocols.rst b/docs/zh_CN/migration-guides/protocols.rst deleted file mode 100644 index ef5f85ce7c..0000000000 --- a/docs/zh_CN/migration-guides/protocols.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/protocols.rst diff --git a/docs/zh_CN/migration-guides/provisioning.rst b/docs/zh_CN/migration-guides/provisioning.rst deleted file mode 100644 index 005d0764e1..0000000000 --- a/docs/zh_CN/migration-guides/provisioning.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/provisioning.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/bluetooth-classic.rst b/docs/zh_CN/migration-guides/release-5.x/bluetooth-classic.rst new file mode 100644 index 0000000000..01cd8f5820 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/bluetooth-classic.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/bluetooth-classic.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/build-system.rst b/docs/zh_CN/migration-guides/release-5.x/build-system.rst new file mode 100644 index 0000000000..d29ad8a817 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/build-system.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/build-system.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/gcc.rst b/docs/zh_CN/migration-guides/release-5.x/gcc.rst new file mode 100644 index 0000000000..532a3c0e03 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/gcc.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/gcc.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/index.rst b/docs/zh_CN/migration-guides/release-5.x/index.rst new file mode 100644 index 0000000000..3c4a3b45e2 --- /dev/null +++ b/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 diff --git a/docs/zh_CN/migration-guides/tcpip-adapter.rst b/docs/zh_CN/migration-guides/release-5.x/networking.rst similarity index 55% rename from docs/zh_CN/migration-guides/tcpip-adapter.rst rename to docs/zh_CN/migration-guides/release-5.x/networking.rst index 0cd8123c3a..933df8ca17 100644 --- a/docs/zh_CN/migration-guides/tcpip-adapter.rst +++ b/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` 的过程。 diff --git a/docs/zh_CN/migration-guides/release-5.x/peripherals.rst b/docs/zh_CN/migration-guides/release-5.x/peripherals.rst new file mode 100644 index 0000000000..0f56c38001 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/peripherals.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/peripherals.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/protocols.rst b/docs/zh_CN/migration-guides/release-5.x/protocols.rst new file mode 100644 index 0000000000..47b0509019 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/protocols.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/protocols.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/provisioning.rst b/docs/zh_CN/migration-guides/release-5.x/provisioning.rst new file mode 100644 index 0000000000..2664b06a35 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/provisioning.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/provisioning.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/removed-components.rst b/docs/zh_CN/migration-guides/release-5.x/removed-components.rst new file mode 100644 index 0000000000..49e8a99abe --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/removed-components.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/removed-components.rst diff --git a/docs/zh_CN/migration-guides/release-5.x/storage.rst b/docs/zh_CN/migration-guides/release-5.x/storage.rst new file mode 100644 index 0000000000..5022a34040 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/storage.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/storage.rst \ No newline at end of file diff --git a/docs/zh_CN/migration-guides/release-5.x/system.rst b/docs/zh_CN/migration-guides/release-5.x/system.rst new file mode 100644 index 0000000000..6a308b2a8a --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/system.rst @@ -0,0 +1 @@ +.. include:: ../../../en/migration-guides/release-5.x/system.rst diff --git a/docs/zh_CN/migration-guides/tools.rst b/docs/zh_CN/migration-guides/release-5.x/tools.rst similarity index 78% rename from docs/zh_CN/migration-guides/tools.rst rename to docs/zh_CN/migration-guides/release-5.x/tools.rst index 55589245ee..9237be63f1 100644 --- a/docs/zh_CN/migration-guides/tools.rst +++ b/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 的图形用户界面等选项。此外，还可以使用 `支持的插件 `，设置基于 VSCode 的环境。 diff --git a/docs/zh_CN/migration-guides/removed-components.rst b/docs/zh_CN/migration-guides/removed-components.rst deleted file mode 100644 index 182e7529ee..0000000000 --- a/docs/zh_CN/migration-guides/removed-components.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/removed-components.rst diff --git a/docs/zh_CN/migration-guides/storage.rst b/docs/zh_CN/migration-guides/storage.rst deleted file mode 100644 index b3ee13e331..0000000000 --- a/docs/zh_CN/migration-guides/storage.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/storage.rst \ No newline at end of file diff --git a/docs/zh_CN/migration-guides/system.rst b/docs/zh_CN/migration-guides/system.rst deleted file mode 100644 index 3d1222cb1d..0000000000 --- a/docs/zh_CN/migration-guides/system.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/migration-guides/system.rst diff --git a/docs/zh_CN/migration-guides/windows-env.rst b/docs/zh_CN/migration-guides/windows-env.rst deleted file mode 100644 index 6c655f8924..0000000000 --- a/docs/zh_CN/migration-guides/windows-env.rst +++ /dev/null @@ -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 的图形用户界面等选项。此外，还可以使用 `支持的插件 `，设置基于 VSCode 的环境。