mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/add_cn_trans_for_migration_guides_system' into 'master'
Docs: add cn trans for migration-guides/system Closes DOC-3324 See merge request espressif/esp-idf!19046
This commit is contained in:
Mo Fei Fei
commit
0d6de25d1c
@ -1,46 +1,51 @@
|
|||||||
System
|
System
|
||||||
======
|
======
|
||||||
|
|
||||||
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
Inter-Processor Call
|
Inter-Processor Call
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
IPC (Inter-Processor Call) component has been moved to ``esp_system``.
|
IPC (Inter-Processor Call) feature is no longer a stand-alone component and has been integrated into the ``esp_system`` component.
|
||||||
|
|
||||||
Thus, any project presenting a ``CMakeLists.txt`` file with the parameters ``PRIV_REQUIRES esp_ipc`` or ``REQUIRES esp_ipc``, should be modified to simply remove these options as ``esp_system`` component is included by default.
|
Thus, any project presenting a ``CMakeLists.txt`` file with the parameters ``PRIV_REQUIRES esp_ipc`` or ``REQUIRES esp_ipc`` should be modified to simply remove these options as the ``esp_system`` component is included by default.
|
||||||
|
|
||||||
ESP Clock
|
ESP Clock
|
||||||
---------
|
---------
|
||||||
|
|
||||||
The old headers ``{IDF_TARGET_NAME}/clk.h``, ``esp_clk.h`` have been removed.
|
The ESP Clock API (functions/types/macros prefixed with ``esp_clk``) has been made into a private API. Thus, the previous include paths ``#include "{IDF_TARGET_NAME}/clk.h"`` and ``#include "esp_clk.h"`` have been removed. If users still require usage of the ESP Clock API (though this is not recommended), it can be included via ``#include "esp_private/esp_clk.h"``.
|
||||||
|
|
||||||
Therefore, If you want to use the function with the prefix ``esp_clk`` please include ``esp_private/esp_clk.h`` instead.
|
.. note::
|
||||||
|
|
||||||
|
Private APIs are not stable and no are longer subject to the ESP-IDF versioning scheme's breaking change rules. Thus, it is not recommended for users to continue calling private APIs in their applications.
|
||||||
|
|
||||||
Cache Error Interrupt
|
Cache Error Interrupt
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
The old headers ``{IDF_TARGET_NAME}/cache_err_int.h`` have been removed. Please include ``esp_private/cache_err_int.h`` instead.
|
The Cache Error Interrupt API (functions/types/macros prefixed with ``esp_cache_err``) has been made into a private API. Thus, the previous include path ``#include "{IDF_TARGET_NAME}/cache_err_int.h"`` has been removed. If users still require usage of the Cache Error Interrupt API (though this is not recommended), it can be included via ``#include "esp_private/cache_err_int.h"``.
|
||||||
|
|
||||||
Bootloader Support
|
bootloader_support
|
||||||
------------------
|
--------------------
|
||||||
|
|
||||||
* The function ``bootloader_common_get_reset_reason()`` has been removed. Please use the function ``esp_rom_get_reset_reason()`` in the ROM component.
|
* The function ``bootloader_common_get_reset_reason()`` has been removed. Please use the function ``esp_rom_get_reset_reason()`` in the ROM component.
|
||||||
* The functions ``esp_secure_boot_verify_sbv2_signature_block()`` and ``esp_secure_boot_verify_rsa_signature_block()`` have been removed without replacement. We don't expect users to use these directly. If they are indeed still neccessary, please open a feature request on github explaining why these functions are necessary to you.
|
* The functions ``esp_secure_boot_verify_sbv2_signature_block()`` and ``esp_secure_boot_verify_rsa_signature_block()`` have been removed without replacement. We do not expect users to use these directly. If they are indeed still neccessary, please open a feature request on `GitHub <https://github.com/espressif/esp-idf/issues/new/choose>`_ explaining why these functions are necessary to you.
|
||||||
|
|
||||||
Brownout
|
Brownout
|
||||||
--------
|
--------
|
||||||
|
|
||||||
The header ``brownout.h`` has been made private. ESP-IDF developers should include ``esp_private/brownout.h`` instead.
|
The Brownout API (functions/types/macros prefixed with ``esp_brownout``) has been made into a private API. Thus, the previous include path ``#include "brownout.h"`` has been removed. If users still require usage of the Brownout API (though this is not recommended), it can be included via ``#include "esp_private/brownout.h"``.
|
||||||
|
|
||||||
Trax
|
Trax
|
||||||
----
|
----
|
||||||
|
|
||||||
The header ``trax.h`` has been made private. ESP-IDF developers should include ``esp_private/trax.h`` instead.
|
The Trax API (functions/types/macros prefixed with ``trax_``) has been made into a private API. Thus, the previous include path ``#include "trax.h"`` has been removed. If users still require usage of the Trax API (though this is not recommended), it can be included via ``#include "esp_private/trax.h"``.
|
||||||
|
|
||||||
ROM
|
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``).
|
|
||||||
|
|
||||||
ESP HW Support
|
The previously deprecated ROM-related header files located in ``components/esp32/rom/`` (old include path: ``rom/*.h``) have been moved. Please 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
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
- The header files ``soc/cpu.h`` have been deleted and deprecated CPU util functions have been removed. ESP-IDF developers should include ``esp_cpu.h`` instead for equivalent functions.
|
- The header files ``soc/cpu.h`` have been deleted and deprecated CPU util functions have been removed. ESP-IDF developers should include ``esp_cpu.h`` instead for equivalent functions.
|
||||||
@ -48,53 +53,55 @@ ESP HW Support
|
|||||||
- The header file ``compare_set.h`` have been deleted. ESP-IDF developers should use ``esp_cpu_compare_and_set()`` function provided in ``esp_cpu.h`` instead.
|
- The header file ``compare_set.h`` have been deleted. ESP-IDF developers should use ``esp_cpu_compare_and_set()`` function provided in ``esp_cpu.h`` instead.
|
||||||
- ``esp_cpu_get_ccount()``, ``esp_cpu_set_ccount()`` and ``esp_cpu_in_ocd_debug_mode()`` were removed from ``esp_cpu.h``. ESP-IDF developers should use respectively ``esp_cpu_get_cycle_count()``, ``esp_cpu_set_cycle_count()`` and ``esp_cpu_dbgr_is_attached()`` instead.
|
- ``esp_cpu_get_ccount()``, ``esp_cpu_set_ccount()`` and ``esp_cpu_in_ocd_debug_mode()`` were removed from ``esp_cpu.h``. ESP-IDF developers should use respectively ``esp_cpu_get_cycle_count()``, ``esp_cpu_set_cycle_count()`` and ``esp_cpu_dbgr_is_attached()`` instead.
|
||||||
- The header file ``esp_intr.h`` has been deleted. Please include ``esp_intr_alloc.h`` to allocate and manipulate interrupts.
|
- The header file ``esp_intr.h`` has been deleted. Please include ``esp_intr_alloc.h`` to allocate and manipulate interrupts.
|
||||||
- The header file ``esp_panic.h`` has been deleted. ESP-IDF developers should include ``esp_private/panic_reason.h`` to get supported panic reasons. And should include ``esp_debug_helpers.h`` to use any debug related helper functions, e.g. print backtrace.
|
- The Panic API (functions/types/macros prefixed with ``esp_panic``) has been made into a private API. Thus, the previous include path ``#include "esp_panic.h"`` has been removed. If users still require usage of the Trax API (though this is not recommended), it can be included via ``#include "esp_private/panic_reason.h"``. Besides, developers should include ``esp_debug_helpers.h`` instead to use any debug-related helper functions, e.g., print backtrace.
|
||||||
- The header file ``soc_log.h`` is now renamed to ``esp_hw_log.h`` and all logging macros have been updated from ``SOC_LOGx`` to ``ESP_HW_LOGx``. ESP-IDF users must use the later form.
|
- The header file ``soc_log.h`` is now renamed to ``esp_hw_log.h`` and all logging macros have been updated from ``SOC_LOGx`` to ``ESP_HW_LOGx``. ESP-IDF users should use the updated macro names.
|
||||||
- The header files ``spinlock.h``, ``clk_ctrl_os.h`` and ``rtc_wdt.h`` must now be included without the ``soc`` prefix. Eg:- ``#include "spinlock.h"``.
|
- The header files ``spinlock.h``, ``clk_ctrl_os.h``, and ``rtc_wdt.h`` must now be included without the ``soc`` prefix. For example, ``#include "spinlock.h"``.
|
||||||
- ``esp_chip_info()`` returns the chip version in the format = 100 * ``major eFuse version`` + ``minor eFuse version``. Thus, the ``revision`` in the ``esp_chip_info_t`` structure is expanded to uint16_t to fit the new format.
|
- ``esp_chip_info()`` returns the chip version in the format = 100 * ``major eFuse version`` + ``minor eFuse version``. Thus, the ``revision`` in the ``esp_chip_info_t`` structure is expanded to uint16_t to fit the new format.
|
||||||
|
|
||||||
PSRAM
|
PSRAM
|
||||||
^^^^^
|
^^^^^
|
||||||
- The target specific header files ``spiram.h`` have been deleted. The header file ``esp_spiram.h`` has been deleted. A new component ``esp_psram`` is created, you should include ``esp_psram.h`` instead. Besides, you might need to add ``esp_psram`` component to the list of component requirements in CMakeLists.txt.
|
|
||||||
|
- The target-specific header file ``spiram.h`` and the header file ``esp_spiram.h`` have been removed. A new component ``esp_psram`` is created instead. For PSRAM/SPIRAM-related functions, users now include ``esp_psram.h`` and set the ``esp_psram`` component as a component requirement in their ``CMakeLists.txt`` project files.
|
||||||
- ``esp_spiram_get_chip_size`` and ``esp_spiram_get_size`` have been deleted. You should use ``esp_psram_get_size`` instead.
|
- ``esp_spiram_get_chip_size`` and ``esp_spiram_get_size`` have been deleted. You should use ``esp_psram_get_size`` instead.
|
||||||
|
|
||||||
Efuse
|
eFuse
|
||||||
----------
|
----------
|
||||||
|
|
||||||
The parameter type of function ``esp_secure_boot_read_key_digests()`` changed from ``ets_secure_boot_key_digests_t*`` to ``esp_secure_boot_key_digests_t*``. ``ets_secure_boot_key_digests_t*``. The new type is the same as the old one, except that the ``allow_key_revoke`` flag has been removed. The latter was always set to ``true`` in current code, hence, it didn't provide additional information.
|
- The parameter type of function ``esp_secure_boot_read_key_digests()`` changed from ``ets_secure_boot_key_digests_t*`` to ``esp_secure_boot_key_digests_t*``. The new type is the same as the old one, except that the ``allow_key_revoke`` flag has been removed. The latter was always set to ``true`` in current code, not providing additional information.
|
||||||
|
- Added eFuse wafer revisions: major and minor. The ``esp_efuse_get_chip_ver()`` API is not compatible with these changes, so it was removed. Instead, please use the following APIs: ``efuse_hal_get_major_chip_version()``, ``efuse_hal_get_minor_chip_version()`` or ``efuse_hal_chip_revision()``.
|
||||||
|
|
||||||
ESP Common
|
esp_common
|
||||||
----------
|
------------
|
||||||
|
``EXT_RAM_ATTR`` is deprecated. Use the 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
|
||||||
|
------------
|
||||||
|
- The header files ``esp_random.h``, ``esp_mac.h``, and ``esp_chip_info.h``, which were all previously indirectly included via the header file ``esp_system.h``, must now be included directly. These indirect inclusions from ``esp_system.h`` have been removed.
|
||||||
|
- The Backtrace Parser API (functions/types/macros prefixed with ``esp_eh_frame_``) has been made into a private API. Thus, the previous include path ``#include "eh_frame_parser.h"`` has been removed. If users still require usage of the Backtrace Parser API (though this is not recommended), it can be included via ``#include "esp_private/eh_frame_parser.h"``.
|
||||||
|
- The Interrupt Watchdog API (functions/types/macros prefixed with ``esp_int_wdt_``) has been made into a private API. Thus, the previous include path ``#include "esp_int_wdt.h"`` has been removed. If users still require usage of the Interrupt Watchdog API (though this is not recommended), it can be included via ``#include "esp_private/esp_int_wdt.h"``.
|
||||||
|
|
||||||
ESP System
|
SOC Dependency
|
||||||
----------
|
|
||||||
- The header files ``esp_random.h``, ``esp_mac.h`` and ``esp_chip_info.h``, which were all previously indirectly included via the header file ``esp_system.h``, must now be included directly. These headers are removed from ``esp_system.h``.
|
|
||||||
- The header file ``eh_frame_parser.h`` must now be included with a ``esp_private`` prefix like ``#include "esp_private/eh_frame_parser.h"``.
|
|
||||||
- The header file ``esp_int_wdt.h`` must now be included with a ``esp_private`` prefix like ``#include "esp_private/esp_int_wdt.h"``.
|
|
||||||
|
|
||||||
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.
|
- Public API headers listed in the Doxyfiles will not expose unstable and unnecessary soc header files, such as ``soc/soc.h`` and ``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.
|
- 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
|
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 no longer need to choose the group and timer ID.
|
||||||
|
|
||||||
ESP Timer
|
esp_timer
|
||||||
|
-----------
|
||||||
|
|
||||||
|
The FRC2-based legacy implementation of esp_timer available on ESP32 has been removed. The simpler and more efficient implementation based on the LAC timer is now the only option.
|
||||||
|
|
||||||
|
ESP Image
|
||||||
---------
|
---------
|
||||||
|
|
||||||
Removed the FRC2 based legacy implementation of esp_timer available on ESP32. The simpler and more efficient implementation based on the LAC timer is now the only option.
|
The image SPI speed enum definitions have been renamed.
|
||||||
|
|
||||||
ESP image
|
|
||||||
---------
|
|
||||||
|
|
||||||
Rename the image SPI speed enum definition.
|
|
||||||
- Enum ``ESP_IMAGE_SPI_SPEED_80M`` has been renamed to ``ESP_IMAGE_SPI_SPEED_DIV_1``.
|
- Enum ``ESP_IMAGE_SPI_SPEED_80M`` has been renamed to ``ESP_IMAGE_SPI_SPEED_DIV_1``.
|
||||||
- Enum ``ESP_IMAGE_SPI_SPEED_40M`` has been renamed to ``ESP_IMAGE_SPI_SPEED_DIV_2``.
|
- Enum ``ESP_IMAGE_SPI_SPEED_40M`` has been renamed to ``ESP_IMAGE_SPI_SPEED_DIV_2``.
|
||||||
- Enum ``ESP_IMAGE_SPI_SPEED_26M`` has been renamed to ``ESP_IMAGE_SPI_SPEED_DIV_3``.
|
- Enum ``ESP_IMAGE_SPI_SPEED_26M`` has been renamed to ``ESP_IMAGE_SPI_SPEED_DIV_3``.
|
||||||
@ -103,15 +110,10 @@ Rename the image SPI speed enum definition.
|
|||||||
Task Watchdog Timers
|
Task Watchdog Timers
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
- The API for ``esp_task_wdt_init()`` has changed as follows
|
- The API for ``esp_task_wdt_init()`` has changed as follows:
|
||||||
|
|
||||||
- Configuration is now passed as a configuration structure.
|
- Configuration is now passed as a configuration structure.
|
||||||
- The function will now handle subscribing of the idle tasks if configured to do so
|
- The function will now handle subscribing of the idle tasks if configured to do so.
|
||||||
|
|
||||||
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
|
FreeRTOS
|
||||||
--------
|
--------
|
||||||
@ -119,24 +121,24 @@ FreeRTOS
|
|||||||
Legacy API and Data Types
|
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:
|
Previously, the ``configENABLE_BACKWARD_COMPATIBILITY`` option was set by default, thus allowing 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 do one of the followings:
|
||||||
|
|
||||||
- Update their code to remove usage of legacy FreeRTOS names/types
|
- 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
|
- Enable the :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` to explicitly allow the usage of legacy names/types.
|
||||||
|
|
||||||
Tasks Snapshot
|
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 header ``task_snapshot.h`` has been removed from ``freertos/task.h``. ESP-IDF developers should include ``freertos/task_snapshot.h`` if they need tasks snapshot API.
|
||||||
|
|
||||||
The function :cpp:func:`vTaskGetSnapshot` now returns ``BaseType_t``. Return value shall be ``pdTRUE`` on success and ``pdFALSE`` otherwise.
|
The function :cpp:func:`vTaskGetSnapshot` now returns ``BaseType_t``. Return value shall be ``pdTRUE`` on success and ``pdFALSE`` otherwise.
|
||||||
|
|
||||||
FreeRTOS Asserts
|
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``.
|
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
|
Port Macro API
|
||||||
^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
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:
|
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:
|
||||||
@ -147,4 +149,3 @@ The file ``portmacro_deprecated.h`` which was added to maintain backward compati
|
|||||||
- ``vPortCPUAcquireMutex()`` is removed. Users should use the ``spinlock_acquire()`` function instead.
|
- ``vPortCPUAcquireMutex()`` is removed. Users should use the ``spinlock_acquire()`` function instead.
|
||||||
- ``vPortCPUAcquireMutexTimeout()`` 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.
|
- ``vPortCPUReleaseMutex()`` is removed. Users should use the ``spinlock_release()`` function instead.
|
||||||
|
|
||||||
|
|||||||
@ -1 +1,151 @@
|
|||||||
.. include:: ../../../en/migration-guides/release-5.x/system.rst
|
系统
|
||||||
|
======
|
||||||
|
|
||||||
|
:link_to_translation:`en:[英文]`
|
||||||
|
|
||||||
|
跨核执行
|
||||||
|
----------
|
||||||
|
|
||||||
|
跨核执行 (Inter-Processor Call, IPC) 不再是一个独立组件，现已被包含至 ``esp_system``。
|
||||||
|
|
||||||
|
因此，若项目的 ``CMakeLists.txt`` 文件中出现 ``PRIV_REQUIRES esp_ipc`` 或 ``REQUIRES esp_ipc``，应删除这些选项，因为项目中已默认包含 ``esp_system`` 组件。
|
||||||
|
|
||||||
|
ESP 时钟
|
||||||
|
---------
|
||||||
|
|
||||||
|
ESP 时钟 API（即以 ``esp_clk`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "{IDF_TARGET_NAME}/clk.h"`` 和 ``#include "esp_clk.h"`` 已被移除。如仍需使用 ESP 时钟 API（并不推荐），请使用 ``#include "esp_private/esp_clk.h"`` 来包含。
|
||||||
|
|
||||||
|
.. 注意::
|
||||||
|
|
||||||
|
私有 API 不属于稳定的 API，不会遵循 ESP-IDF 的版本演进规则，因此不推荐用户在应用中使用。
|
||||||
|
|
||||||
|
缓存错误中断
|
||||||
|
--------------
|
||||||
|
|
||||||
|
缓存错误中断 API（即以 ``esp_cache_err`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "{IDF_TARGET_NAME}/cache_err_int.h"`` 已被移除。如仍需使用缓存错误中断 API（并不推荐），请使用 ``#include "esp_private/cache_err_int.h"`` 来包含。
|
||||||
|
|
||||||
|
bootloader_support
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
* 函数 ``bootloader_common_get_reset_reason()`` 已被移除。请使用 ROM 组件中的函数 ``esp_rom_get_reset_reason()``。
|
||||||
|
* 函数 ``esp_secure_boot_verify_sbv2_signature_block()`` 和 ``esp_secure_boot_verify_rsa_signature_block()`` 已被移除，无新的替换函数。不推荐用户直接使用以上函数。如确需要，请在 `GitHub <https://github.com/espressif/esp-idf/issues/new/choose>`_ 上对该功能提交请求，并解释您需要此函数的原因。
|
||||||
|
|
||||||
|
断电
|
||||||
|
--------
|
||||||
|
|
||||||
|
断电 API（即以 ``esp_brownout`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "brownout.h"`` 已被移除。如仍需使用断电 API（并不推荐），请使用 ``#include "esp_private/brownout.h"`` 来包含。
|
||||||
|
|
||||||
|
Trax
|
||||||
|
----
|
||||||
|
|
||||||
|
Trax API（即以 ``trax_`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "trax.h"`` 已被移除。如仍需使用 Trax API（并不推荐），请使用 ``#include "esp_private/trax.h"`` 来包含。
|
||||||
|
|
||||||
|
ROM
|
||||||
|
---
|
||||||
|
|
||||||
|
``components/esp32/rom/`` 路径下存放的已弃用的 ROM 相关头文件已被移除（原包含路径为 ``rom/*.h``）。请使用新的特定目标的路径 ``components/esp_rom/include/{IDF_TARGET_NAME}/``（新的包含路径为 ``{IDF_TARGET_NAME}/rom/*.h``）。
|
||||||
|
|
||||||
|
esp_hw_support
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
- 头文件 ``soc/cpu.h`` 及弃用的 CPU util 函数都已被移除。请包含 ``esp_cpu.h`` 来代替相同功能的函数。
|
||||||
|
- 头文件 ``hal/cpu_ll.h``、``hal/cpu_hal.h``、``hal/soc_ll.h``、``hal/soc_hal.h`` 和 ``interrupt_controller_hal.h`` 的 CPU API 函数已弃用。请包含 ``esp_cpu.h`` 来代替相同功能的函数。
|
||||||
|
- 头文件 ``compare_set.h`` 已被移除。请使用 ``esp_cpu.h`` 中提供的 ``esp_cpu_compare_and_set()`` 函数来代替。
|
||||||
|
- ``esp_cpu_get_ccount()``、``esp_cpu_set_ccount()`` 和 ``esp_cpu_in_ocd_debug_mode()`` 已从 ``esp_cpu.h`` 中移除。请分别使用 ``esp_cpu_get_cycle_count()``、``esp_cpu_set_cycle_count()`` 和 ``esp_cpu_dbgr_is_attached()`` 代替。
|
||||||
|
- 头文件 ``esp_intr.h`` 已被移除。请包含 ``esp_intr_alloc.h`` 以分配和操作中断。
|
||||||
|
- Panic API（即以 ``esp_panic`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "esp_panic.h"`` 已被移除。如仍需使用 Panic API（并不推荐），请使用 ``#include "esp_private/panic_reason.h"`` 来包含。此外，请包含 ``esp_debug_helpers.h`` 以使用与调试有关的任意辅助函数，如打印回溯。
|
||||||
|
- 头文件 ``soc_log.h`` 现更名为 ``esp_hw_log.h``，所有日志宏也从 ``SOC_LOGx`` 更新为 ``ESP_HW_LOGx``。请使用更新后的格式。
|
||||||
|
- 包含头文件 ``spinlock.h``、``clk_ctrl_os.h`` 和 ``rtc_wdt.h`` 时不应当使用 ``soc`` 前缀，如 ``#include "spinlock.h"``。
|
||||||
|
- ``esp_chip_info()`` 命令返回芯片版本，格式为 = 100 * ``主要 eFuse 版本`` + ``次要 eFuse 版本``。因此，为适应新格式， ``esp_chip_info_t`` 结构体中的 ``revision`` 被扩展为 uint16_t。
|
||||||
|
|
||||||
|
PSRAM
|
||||||
|
^^^^^
|
||||||
|
|
||||||
|
- 针对特定目标的头文件 ``spiram.h`` 及头文件 ``esp_spiram.h`` 已被移除，创建新组件 ``esp_psram``。对于与 PSRAM 或 SPIRAM 相关的函数，请包含 ``esp_psram.h``，并在 CMakeLists.txt 项目文件中将 ``esp_psram`` 设置为必需组件。
|
||||||
|
- ``esp_spiram_get_chip_size`` 和 ``esp_spiram_get_size`` 已被移除，请使用 ``esp_psram_get_size``。
|
||||||
|
|
||||||
|
eFuse
|
||||||
|
-------
|
||||||
|
|
||||||
|
- 函数 ``esp_secure_boot_read_key_digests()`` 的参数类型从 ``ets_secure_boot_key_digests_t*`` 更新为 ``esp_secure_boot_key_digests_t*``。新类型与旧类型相同，仅移除了 ``allow_key_revoke`` 标志。在当前代码中，后者总是被设置为 ``true``，并未提供额外信息。
|
||||||
|
- 针对 eFuse 晶圆增加主要修订版本和次要修订版本。API ``esp_efuse_get_chip_ver()`` 与新修订不兼容，因此已被移除。请使用 API ``efuse_hal_get_major_chip_version()``、``efuse_hal_get_minor_chip_version()`` 或 ``efuse_hal_chip_revision()`` 来代替原有 API。
|
||||||
|
|
||||||
|
esp_common
|
||||||
|
------------
|
||||||
|
``EXT_RAM_ATTR`` 已被弃用。请使用新的宏 ``EXT_RAM_BSS_ATTR`` 以将 .bss 放在 PSRAM 上。
|
||||||
|
|
||||||
|
esp_system
|
||||||
|
------------
|
||||||
|
- 头文件 ``esp_random.h``、``esp_mac.h`` 和 ``esp_chip_info.h`` 以往都是通过头文件 ``esp_system.h`` 间接包含，更新后必须直接包含。已移除从 ``esp_system.h`` 中的间接包含功能。
|
||||||
|
- 回溯解析器 API（即以 ``esp_eh_frame_`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "eh_frame_parser.h"`` 已被移除。如仍需使用回溯解析器 API（并不推荐），请使用 ``#include "esp_private/eh_frame_parser.h"`` 来包含。
|
||||||
|
- 中断看门狗定时器 API（即以 ``esp_int_wdt_`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "esp_int_wdt.h"`` 已被移除。如仍需使用中断看门狗定时器 API（并不推荐），请使用 ``#include "esp_private/esp_int_wdt.h"`` 来包含。
|
||||||
|
|
||||||
|
SOC 依赖性
|
||||||
|
--------------
|
||||||
|
|
||||||
|
- Doxyfiles 中列出的公共 API 头文件中不会显示不稳定和非必要的 SOC 头文件，如 ``soc/soc.h`` 和 ``soc/rtc.h``。这意味着，如果用户仍然需要这些“缺失”的头文件，就必须在代码中明确包含这些文件。
|
||||||
|
- Kconfig 选项 ``LEGACY_INCLUDE_COMMON_HEADERS`` 也已被移除。
|
||||||
|
- 头文件 ``soc/soc_memory_types.h`` 已被弃用。请使用 ``esp_memory_utils.h``。包含 ``soc/soc_memory_types.h`` 将触发构建警告，如 ``soc_memory_types.h is deprecated, please migrate to esp_memory_utils.h``。
|
||||||
|
|
||||||
|
应用跟踪
|
||||||
|
--------
|
||||||
|
|
||||||
|
其中一个时间戳源已从定时器组驱动改为新的 :doc:`GPTimer <../../api-reference/peripherals/gptimer>`。Kconfig 选项已重新命名，例如 ``APPTRACE_SV_TS_SOURCE_TIMER00`` 已更改为 ``APPTRACE_SV_TS_SOURCE_GPTIMER``。用户已无需选择组和定时器 ID。
|
||||||
|
|
||||||
|
esp_timer
|
||||||
|
-----------
|
||||||
|
|
||||||
|
基于 FRC2 的 esp_timer 过去可用于 ESP32，现在已被移除，更新后仅可使用更简单有效的 LAC 定时器。
|
||||||
|
|
||||||
|
ESP 镜像
|
||||||
|
---------
|
||||||
|
|
||||||
|
ESP 镜像中关于 SPI 速度的枚举成员已重新更名：
|
||||||
|
|
||||||
|
- ``ESP_IMAGE_SPI_SPEED_80M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_1``。
|
||||||
|
- ``ESP_IMAGE_SPI_SPEED_40M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_2``。
|
||||||
|
- ``ESP_IMAGE_SPI_SPEED_26M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_3``。
|
||||||
|
- ``ESP_IMAGE_SPI_SPEED_20M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_4``。
|
||||||
|
|
||||||
|
任务看门狗定时器
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
- API ``esp_task_wdt_init()`` 更新后有如下变化：
|
||||||
|
|
||||||
|
- 以结构体的形式传递配置。
|
||||||
|
- 可将该函数配置为订阅空闲任务。
|
||||||
|
|
||||||
|
FreeRTOS
|
||||||
|
--------
|
||||||
|
|
||||||
|
遗留 API 及数据类型
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
在以往版本中，ESP-IDF 默认设置 ``configENABLE_BACKWARD_COMPATIBILITY`` 选项，因此可使用 FreeRTOS v8.0.0 之前的函数名称和数据类型。该选项现在已默认禁用，因此默认情况下不再支持以往的 FreeRTOS 名称或类型。用户可以选择以下一种解决方式：
|
||||||
|
|
||||||
|
- 更新代码，删除以往的 FreeRTOS 名称或类型。
|
||||||
|
- 启用 :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` 以显式调用这些名称或类型。
|
||||||
|
|
||||||
|
任务快照
|
||||||
|
^^^^^^^^^^
|
||||||
|
|
||||||
|
头文件 ``task_snapshot.h`` 已从 ``freertos/task.h`` 中移除。如需使用任务快照 API，请包含 ``freertos/task_snapshot.h``。
|
||||||
|
|
||||||
|
函数 :cpp:func:`vTaskGetSnapshot` 现返回 ``BaseType_t``，成功时返回值为 ``pdTRUE``，失败则返回 ``pdFALSE``。
|
||||||
|
|
||||||
|
FreeRTOS 断言
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
在以往版本中，FreeRTOS 断言通过 ``FREERTOS_ASSERT`` kconfig 选项独立配置，不同于系统的其他部分。该选项已被移除，现在需要通过 ``COMPILER_OPTIMIZATION_ASSERTION_LEVEL`` 来完成配置。
|
||||||
|
|
||||||
|
FreeRTOS 移植相关的宏
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
已移除用以保证弃用 API 向后兼容性的 ``portmacro_deprecated.h`` 文件。建议使用下列函数来代替弃用 API。
|
||||||
|
|
||||||
|
- ``portENTER_CRITICAL_NESTED()`` 已被移除，请使用 ``portSET_INTERRUPT_MASK_FROM_ISR()`` 宏。
|
||||||
|
- ``portEXIT_CRITICAL_NESTED()`` 已被移除，请使用 ``portCLEAR_INTERRUPT_MASK_FROM_ISR()`` 宏。
|
||||||
|
- ``vPortCPUInitializeMutex()`` 已被移除，请使用 ``spinlock_initialize()`` 函数。
|
||||||
|
- ``vPortCPUAcquireMutex()`` 已被移除，请使用 ``spinlock_acquire()`` 函数。
|
||||||
|
- ``vPortCPUAcquireMutexTimeout()`` 已被移除，请使用 ``spinlock_acquire()`` 函数。
|
||||||
|
- ``vPortCPUReleaseMutex()`` 已被移除，请使用 ``spinlock_release()`` 函数。
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user