esp-idf/docs/en/migration-guides/freertos.rst

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.
freertos: remove FREERTOS_ASSERT option Freertos asserts are now configured the same way as all other asserts in IDF, i.e. by configuring COMPILER_OPTIMIZATION_ASSERTION_LEVEL. 2021-12-27 23:54:31 -05:00			`Migrate FreeRTOS to ESP-IDF 5.0`
			`==================================`

freertos: Remove legacy data types This commit removes the usage of all legacy FreeRTOS data types that are exposed via configENABLE_BACKWARD_COMPATIBILITY. Legacy types can still be used by enabling CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY. 2022-02-08 04:39:38 -05:00			`Legacy API and Data Types`
			`-------------------------`

minor typo fix 2022-03-16 13:59:04 -04:00			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:
freertos: Remove legacy data types This commit removes the usage of all legacy FreeRTOS data types that are exposed via configENABLE_BACKWARD_COMPATIBILITY. Legacy types can still be used by enabling CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY. 2022-02-08 04:39:38 -05:00
			`- 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

freertos: remove FREERTOS_ASSERT option Freertos asserts are now configured the same way as all other asserts in IDF, i.e. by configuring COMPILER_OPTIMIZATION_ASSERTION_LEVEL. 2021-12-27 23:54:31 -05:00			`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.

docs: add migration guide note about `vTaskGetSnapshot` signature 2022-05-10 02:10:47 -04:00			The function :cpp:func:`vTaskGetSnapshot` now returns ``BaseType_t``. Return value shall be ``pdTRUE`` on success and ``pdFALSE`` otherwise.
freertos: remove FREERTOS_ASSERT option Freertos asserts are now configured the same way as all other asserts in IDF, i.e. by configuring COMPILER_OPTIMIZATION_ASSERTION_LEVEL. 2021-12-27 23:54:31 -05:00
			`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`.
freertos: remove portmacro_deprtecated.h file This commit removes the portmacro_deprecated.h file and the deprecated APIs contained in it. Alternate APIs to use are noted in the migration guide. 2022-03-31 06:26:53 -04:00
			`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.