docs: link to FreeRTOS APIs from SMP changes documentation

docs/api-guides/freertos-smp.rst

@@ -20,8 +20,8 @@ found via http://www.freertos.org/a00106.html
 port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported
 to ESP-IDF.
 
-:ref:`tasks-and-task-creation`: Use ``xTaskCreatePinnedToCore()`` or 
+:ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or 
-``xTaskCreateStaticPinnedToCore()`` to create tasks in ESP-IDF FreeRTOS. The 
+:cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The 
 last parameter of the two functions is ``xCoreID``. This parameter specifies 
 which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**, 
 ``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on
@@ -34,13 +34,13 @@ enter a blocked state, or are distributed across a wider range of priorities.
 
 :ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only 
 affect the scheduler on the the calling core. In other words, calling 
-``vTaskSuspendAll()`` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and
+:cpp:func:`vTaskSuspendAll` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and
 vice versa. Use critical sections or semaphores instead for simultaneous
 access protection.
 
 :ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU** 
-are not synchronized. Do not expect to use ``vTaskDelay`` or 
+are not synchronized. Do not expect to use :cpp:func:`vTaskDelay` or 
-``vTaskDelayUntil`` as an accurate method of synchronizing task execution 
+:cpp:func:`vTaskDelayUntil` as an accurate method of synchronizing task execution 
 between the two cores. Use a counting semaphore instead as their context 
 switches are not tied to tick interrupts due to preemption.
 
@@ -51,15 +51,15 @@ unaffected. If the other core attemps to take same mutex, it will spin until
 the calling core has released the mutex by exiting the critical section.
 
 :ref:`floating-points`: The ESP32 supports hardware acceleration of single
-precision floating point arithmetic (`float`). However the use of hardware
+precision floating point arithmetic (``float``). However the use of hardware
 acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS.
-Therefore, tasks that utilize `float` will automatically be pinned to a core if 
+Therefore, tasks that utilize ``float`` will automatically be pinned to a core if 
-not done so already. Furthermore, `float` cannot be used in interrupt service 
+not done so already. Furthermore, ``float`` cannot be used in interrupt service 
 routines.
 
 :ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS 
 v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately 
-when `vTaskDelete()` is called to delete a task that is not currently running 
+when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running 
 and not pinned to the other core. Otherwise, freeing of task memory will still 
 be delegated to the Idle Task.
 
@@ -67,7 +67,7 @@ be delegated to the Idle Task.
 Storage Pointers (TLSP) feature. However the extra feature of Deletion Callbacks has been
 added. Deletion callbacks are called automatically during task deletion and are
 used to free memory pointed to by TLSP. Call 
-``vTaskSetThreadLocalStoragePointerAndDelCallback()`` to set TLSP and Deletion
+:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback()` to set TLSP and Deletion
 Callbacks.
 
 :ref:`FreeRTOS Hooks<hooks_api_reference>`: Vanilla FreeRTOS Hooks were not designed for SMP.
@@ -94,34 +94,34 @@ This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The
 in order for static allocation functions to be available. Once enabled, the 
 following functions can be called...
 
- - ``xTaskCreateStatic()`` See :ref:`backporting-notes` below
+ - :cpp:func:`xTaskCreateStatic` (see :ref:`backporting-notes` below)
- - ``xQueueCreateStatic()``
+ - :c:macro:`xQueueCreateStatic`
- - ``xSemaphoreCreateBinaryStatic()``
+ - :c:macro:`xSemaphoreCreateBinaryStatic`
- - ``xSemaphoreCreateCountingStatic()``
+ - :c:macro:`xSemaphoreCreateCountingStatic`
- - ``xSemaphoreCreateMutexStatic()``
+ - :c:macro:`xSemaphoreCreateMutexStatic`
- - ``xSemaphoreCreateRecursiveMutexStatic()``
+ - :c:macro:`xSemaphoreCreateRecursiveMutexStatic`
- - ``xTimerCreateStatic()``  See :ref:`backporting-notes` below
+ - :cpp:func:`xTimerCreateStatic`  (see :ref:`backporting-notes` below)
- - ``xEventGroupCreateStatic()``
+ - :cpp:func:`xEventGroupCreateStatic`
 
 Other Features
 ^^^^^^^^^^^^^^
 
- - ``vTaskSetThreadLocalStoragePointer()`` See :ref:`backporting-notes` below
+ - :cpp:func:`vTaskSetThreadLocalStoragePointer` (see :ref:`backporting-notes` below)
- - ``pvTaskGetThreadLocalStoragePointer()`` See :ref:`backporting-notes` below
+ - :cpp:func:`pvTaskGetThreadLocalStoragePointer` (see :ref:`backporting-notes` below)
- - ``vTimerSetTimerID()``
+ - :cpp:func:`vTimerSetTimerID`
- - ``xTimerGetPeriod()``
+ - :cpp:func:`xTimerGetPeriod`
- - ``xTimerGetExpiryTime()``
+ - :cpp:func:`xTimerGetExpiryTime`
- - ``pcQueueGetName()``
+ - :cpp:func:`pcQueueGetName`
- - ``uxSemaphoreGetCount()``
+ - :c:macro:`uxSemaphoreGetCount`
 
 .. _backporting-notes:
 
 Backporting Notes
 ^^^^^^^^^^^^^^^^^
 
-**1)** ``xTaskCreateStatic`` has been made SMP compatible in a similar 
+**1)** :cpp:func:`xTaskCreateStatic` has been made SMP compatible in a similar 
-fashion to ``xTaskCreate`` (see :ref:`tasks-and-task-creation`). Therefore 
+fashion to :cpp:func:`xTaskCreate` (see :ref:`tasks-and-task-creation`). Therefore 
-``xTaskCreateStaticPinnedToCore()`` can also be called.
+:cpp:func:`xTaskCreateStaticPinnedToCore` can also be called.
 
 **2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to 
 be statically allocated, the daemon task is always dynamically allocated in 
@@ -130,7 +130,7 @@ defined when using statically allocated timers in ESP-IDF FreeRTOS.
 
 **3)** The Thread Local Storage Pointer feature has been modified in ESP-IDF
 FreeRTOS to include Deletion Callbacks (see :ref:`deletion-callbacks`). Therefore
-the function ``vTaskSetThreadLocalStoragePointerAndDelCallback()`` can also be 
+the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can also be 
 called.
 
 
@@ -142,9 +142,9 @@ Tasks and Task Creation
 Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore 
 two new task creation functions have been added to ESP-IDF FreeRTOS by 
 appending ``PinnedToCore`` to the names of the task creation functions in 
-vanilla FreeRTOS. The vanilla FreeRTOS functions of ``xTaskCreate()``
+vanilla FreeRTOS. The vanilla FreeRTOS functions of :cpp:func:`xTaskCreate`
-and ``xTaskCreateStatic()`` have led to the addition of 
+and :cpp:func:`xTaskCreateStatic` have led to the addition of 
-``xTaskCreatePinnedToCore()`` and ``xTaskCreateStaticPinnedToCore()`` in 
+:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in 
 ESP-IDF FreeRTOS (see :ref:`backported-features`).
 
 For more details see :component_file:`freertos/task.c`
@@ -164,9 +164,9 @@ of 1000 bytes. It should be noted that the ``uxStackDepth`` parameter in
 vanilla FreeRTOS specifies a task’s stack depth in terms of the number of 
 words, whereas ESP-IDF FreeRTOS specifies the stack depth in terms of bytes.
 
-Note that the vanilla FreeRTOS functions ``xTaskCreate`` and 
+Note that the vanilla FreeRTOS functions :cpp:func:`xTaskCreate` and 
-``xTaskCreateStatic`` have been macro defined in ESP-IDF FreeRTOS to call 
+:cpp:func:`xTaskCreateStatic` have been defined in ESP-IDF FreeRTOS as inline functions which call 
-``xTaskCreatePinnedToCore()`` and ``xTaskCreateStaticPinnedToCore()``
+:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore`
 respectively with ``tskNO_AFFINITY`` as the ``xCoreID`` value. 
 
 Each Task Control Block (TCB) in ESP-IDF stores the ``xCoreID`` as a member. 
@@ -283,18 +283,18 @@ different cores.
 Scheduler Suspension
 ^^^^^^^^^^^^^^^^^^^^
 
-In vanilla FreeRTOS, suspending the scheduler via ``vTaskSuspendAll()`` will 
+In vanilla FreeRTOS, suspending the scheduler via :cpp:func:`vTaskSuspendAll` will 
-prevent calls of ``vTaskSwitchContext()`` from context switching until the 
+prevent calls of ``vTaskSwitchContext`` from context switching until the 
-scheduler has been resumed with ``vTaskResumeAll()``. However servicing ISRs 
+scheduler has been resumed with :cpp:func:`xTaskResumeAll`. However servicing ISRs 
 are still permitted. Therefore any changes in task states as a result from the
 current running task or ISRSs will not be executed until the scheduler is 
 resumed. Scheduler suspension in vanilla FreeRTOS is a common protection method 
 against simultaneous access of data shared between tasks, whilst still allowing 
 ISRs to be serviced.
 
-In ESP-IDF FreeRTOS, ``vTaskSuspendAll()`` will only prevent calls of 
+In ESP-IDF FreeRTOS, :cpp:func:`xTaskResumeAll` will only prevent calls of 
 ``vTaskSwitchContext()`` from switching contexts on the core that called for the
-suspension. Hence if **PRO_CPU** calls ``vTaskSuspendAll()``, **APP_CPU** will 
+suspension. Hence if **PRO_CPU** calls :cpp:func:`vTaskSuspendAll`, **APP_CPU** will 
 still be able to switch contexts. If data is shared between tasks that are 
 pinned to different cores, scheduler suspension is **NOT** a valid method of 
 protection against simultaneous access. Consider using critical sections 
@@ -302,7 +302,7 @@ protection against simultaneous access. Consider using critical sections
 protecting shared resources in ESP-IDF FreeRTOS.
 
 In general, it's better to use other RTOS primitives like mutex semaphores to protect
-against data shared between tasks, rather than ``vTaskSuspendAll()``.
+against data shared between tasks, rather than :cpp:func:`vTaskSuspendAll`.
 
 
 .. _tick-interrupt-synchronicity:
@@ -316,8 +316,8 @@ each core being independent, and the tick interrupts to each core being
 unsynchronized.
 
 In vanilla FreeRTOS the tick interrupt triggers a call to 
-``xTaskIncrementTick()`` which is responsible for incrementing the tick 
+:cpp:func:`xTaskIncrementTick` which is responsible for incrementing the tick 
-counter, checking if tasks which have called ``vTaskDelay()`` have fulfilled 
+counter, checking if tasks which have called :cpp:func:`vTaskDelay` have fulfilled 
 their delay period, and moving those tasks from the Delayed Task List to the 
 Ready Task List. The tick interrupt will then call the scheduler if a context 
 switch is necessary.
@@ -372,11 +372,11 @@ The ESP-IDF FreeRTOS critical section functions have been modified as follows…
 
  - ``taskENTER_CRITICAL(mux)``, ``taskENTER_CRITICAL_ISR(mux)``, 
    ``portENTER_CRITICAL(mux)``, ``portENTER_CRITICAL_ISR(mux)`` are all macro 
-   defined to call ``vTaskEnterCritical()`` 
+   defined to call :cpp:func:`vTaskEnterCritical` 
 
  - ``taskEXIT_CRITICAL(mux)``, ``taskEXIT_CRITICAL_ISR(mux)``, 
    ``portEXIT_CRITICAL(mux)``, ``portEXIT_CRITICAL_ISR(mux)`` are all macro 
-   defined to call ``vTaskExitCritical()``
+   defined to call :cpp:func:`vTaskExitCritical`
 
 For more details see :component_file:`freertos/include/freertos/portmacro.h` 
 and :component_file:`freertos/task.c`
@@ -394,23 +394,23 @@ Floating Point Aritmetic
 ------------------------
 
 The ESP32 supports hardware acceleration of single precision floating point
-arithmetic (`float`) via Floating Point Units (FPU, also known as coprocessors) 
+arithmetic (``float``) via Floating Point Units (FPU, also known as coprocessors) 
 attached to each core. The use of the FPUs imposes some behavioral restrictions 
 on ESP-IDF FreeRTOS.
 
 ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words,
 the state of a core's FPU registers are not immediately saved when a context 
-switch occurs. Therefore, tasks that utilize `float` must be pinned to a
+switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a
 particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin
 the task in question to whichever core the task was running on upon the task's 
-first use of `float`. Likewise due to Lazy Context Switching, interrupt service 
+first use of ``float``. Likewise due to Lazy Context Switching, interrupt service 
-routines must also not use `float`.
+routines must also not use ``float``.
 
 ESP32 does not support hardware acceleration for double precision floating point
-arithmetic (`double`). Instead `double` is implemented via software hence the 
+arithmetic (``double``). Instead ``double`` is implemented via software hence the 
-behavioral restrictions with regards to `float` do not apply to `double`. Note
+behavioral restrictions with regards to ``float`` do not apply to ``double``. Note
-that due to the lack of hardware acceleration, `double` operations may consume
+that due to the lack of hardware acceleration, ``double`` operations may consume
-significantly larger amount of CPU time in comparison to `float`.
+significantly larger amount of CPU time in comparison to ``float``.
 
 
 .. _task-deletion:
@@ -420,12 +420,12 @@ Task Deletion
 
 FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory 
 entirely to the Idle Task. Currently, the freeing of task memory will occur
-immediately (within `vTaskDelete()`) if the task being deleted is not currently 
+immediately (within :cpp:func:`vTaskDelete`) if the task being deleted is not currently 
 running or is not pinned to the other core (with respect to the core 
-`vTaskDelete()` is called on). TLSP deletion callbacks will also run immediately
+:cpp:func:`vTaskDelete` is called on). TLSP deletion callbacks will also run immediately
 if the same conditions are met.
 
-However, calling `vTaskDelete()` to delete a task that is either currently 
+However, calling :cpp:func:`vTaskDelete` to delete a task that is either currently 
 running or pinned to the other core will still result in the freeing of memory 
 being delegated to the Idle Task.
 
@@ -456,8 +456,8 @@ is the index number of the associated TLSP, and the second parameter is the
 TLSP itself.
 
 Deletion callbacks are set alongside TLSP by calling 
-``vTaskSetThreadLocalStoragePointerAndDelCallback()``. Calling the vanilla 
+:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`. Calling the vanilla 
-FreeRTOS function ``vTaskSetThreadLocalStoragePointer()`` will simply set the
+FreeRTOS function :cpp:func:`vTaskSetThreadLocalStoragePointer` will simply set the
 TLSP's associated Deletion Callback to `NULL` meaning that no callback will be
 called for that TLSP during task deletion. If a deletion callback is `NULL`,
 users should manually free the memory pointed to by the associated TLSP before 
@@ -466,7 +466,7 @@ task deletion in order to avoid memory leak.
 :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used
 to configure the number TLSP and Deletion Callbacks a TCB will have.
 
-For more details see :component_file:`freertos/include/freertos/task.h`
+For more details see :doc:`FreeRTOS API reference<../api-reference/system/freertos>`.
 
 
 .. _esp-idf-freertos-configuration:
@@ -491,7 +491,7 @@ number of Thread Local Storage Pointers each task will have in ESP-IDF
 FreeRTOS.
 
 :ref:`CONFIG_SUPPORT_STATIC_ALLOCATION` will enable the backported
-functionality of ``xTaskCreateStaticPinnedToCore()`` in ESP-IDF FreeRTOS
+functionality of :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS
     
 :ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in
 particular functions in ESP-IDF FreeRTOS which have not been fully tested