Update SMP docs (#400)

This commit adds the docs for newly added SMP APIs.

Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>

2 files changed, 144 insertions, 5 deletions

diff --git a/include/task.h b/include/task.h
index 16339cc2a..808286af2 100644
--- a/include/task.h
+++ b/include/task.h
@@ -172,7 +172,7 @@ typedef enum
 
 /**
  * Defines affinity to all available cores.
- * 
+ *
  */
 #define tskNO_AFFINITY ( ( UBaseType_t ) -1U )
 
@@ -1244,11 +1244,152 @@ void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
 BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
 
 #if ( configUSE_CORE_AFFINITY == 1)
-void vTaskCoreAffinitySet( const TaskHandle_t xTask, UBaseType_t uxCoreAffinityMask );
-UBaseType_t vTaskCoreAffinityGet( const TaskHandle_t xTask );
+    /**
+     * @brief Sets the core affinity mask for a task.
+     *
+     * It sets the cores on which a task can run. configUSE_CORE_AFFINITY must
+     * be defined as 1 for this function to be available.
+     *
+     * @param xTask The handle of the task to set the core affinity mask for.
+     * Passing NULL will set the core affinity mask for the calling task.
+     *
+     * @param uxCoreAffinityMask A bitwise value that indicates the cores on
+     * which the task can run. Cores are numbered from 0 to configNUM_CORES - 1.
+     * For example, to ensure that a task can run on core 0 and core 1, set
+     * uxCoreAffinityMask to 0x03.
+     *
+     * Example usage:
+     *
+     * // The function that creates task.
+     * void vAFunction( void )
+     * {
+     * TaskHandle_t xHandle;
+     * UBaseType_t uxCoreAffinityMask;
+     *
+     *      // Create a task, storing the handle.
+     *      xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &( xHandle ) );
+     *
+     *      // Define the core affinity mask such that this task can only run
+     *      // on core 0 and core 2.
+     *      uxCoreAffinityMask = ( ( 1 << 0 ) | ( 1 << 2 ) );
+     *
+     *      //Set the core affinity mask for the task.
+     *      vTaskCoreAffinitySet( xHandle, uxCoreAffinityMask );
+     * }
+     */
+    void vTaskCoreAffinitySet( const TaskHandle_t xTask, UBaseType_t uxCoreAffinityMask );
 #endif
 
+#if ( configUSE_CORE_AFFINITY == 1)
+    /**
+     * @brief Gets the core affinity mask for a task.
+     *
+     * configUSE_CORE_AFFINITY must be defined as 1 for this function to be
+     * available.
+     *
+     * @param xTask The handle of the task to get the core affinity mask for.
+     * Passing NULL will get the core affinity mask for the calling task.
+     *
+     * @return The core affinity mask which is a bitwise value that indicates
+     * the cores on which a task can run. Cores are numbered from 0 to
+     * configNUM_CORES - 1. For example, if a task can run on core 0 and core 1,
+     * the core affinity mask is 0x03.
+     *
+     * Example usage:
+     *
+     * // Task handle of the networking task - it is populated elsewhere.
+     * TaskHandle_t xNetworkingTaskHandle;
+     *
+     * void vAFunction( void )
+     * {
+     * TaskHandle_t xHandle;
+     * UBaseType_t uxNetworkingCoreAffinityMask;
+     *
+     *     // Create a task, storing the handle.
+     *     xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &( xHandle ) );
+     *
+     *     //Get the core affinity mask for the networking task.
+     *     uxNetworkingCoreAffinityMask = vTaskCoreAffinityGet( xNetworkingTaskHandle );
+     *
+     *     // Here is a hypothetical scenario, just for the example. Assume that we
+     *     // have 2 cores - Core 0 and core 1. We want to pin the application task to
+     *     // the core different than the networking task to ensure that the
+     *     // application task does not interfere with networking.
+     *     if( ( uxNetworkingCoreAffinityMask & ( 1 << 0 ) ) != 0 )
+     *     {
+     *         // The networking task can run on core 0, pin our task to core 1.
+     *         vTaskCoreAffinitySet( xHandle, ( 1 << 1 ) );
+     *     }
+     *     else
+     *     {
+     *         // Otherwise, pin our task to core 0.
+     *         vTaskCoreAffinitySet( xHandle, ( 1 << 0 ) );
+     *     }
+     * }
+     */
+    UBaseType_t vTaskCoreAffinityGet( const TaskHandle_t xTask );
+#endif
+
+/**
+ * @brief Disables preemption for a task.
+ *
+ * @param xTask The handle of the task to disable preemption. Passing NULL
+ * disables preemption for the calling task.
+ *
+ * Example usage:
+ *
+ * void vTaskCode( void *pvParameters )
+ * {
+ *     // Silence warnings about unused parameters.
+ *     ( void ) pvParameters;
+ *
+ *     for( ;; )
+ *     {
+ *         // ... Perform some function here.
+ *
+ *         // Disable preemption for this task.
+ *         vTaskPreemptionDisable( NULL );
+ *
+ *         // The task will not be preempted when it is executing in this portion ...
+ *
+ *         // ... until the preemption is enabled again.
+ *         vTaskPreemptionEnable( NULL );
+ *
+ *         // The task can be preempted when it is executing in this portion.
+ *     }
+ * }
+ */
 void vTaskPreemptionDisable( const TaskHandle_t xTask );
+
+/**
+ * @brief Enables preemption for a task.
+ *
+ * @param xTask The handle of the task to enable preemption. Passing NULL
+ * enables preemption for the calling task.
+ *
+ * Example usage:
+ *
+ * void vTaskCode( void *pvParameters )
+ * {
+ *     // Silence warnings about unused parameters.
+ *     ( void ) pvParameters;
+ *
+ *     for( ;; )
+ *     {
+ *         // ... Perform some function here.
+ *
+ *         // Disable preemption for this task.
+ *         vTaskPreemptionDisable( NULL );
+ *
+ *         // The task will not be preempted when it is executing in this portion ...
+ *
+ *         // ... until the preemption is enabled again.
+ *         vTaskPreemptionEnable( NULL );
+ *
+ *         // The task can be preempted when it is executing in this portion.
+ *     }
+ * }
+ */
 void vTaskPreemptionEnable( const TaskHandle_t xTask );
 
 /*-----------------------------------------------------------
diff --git a/tasks.c b/tasks.c
index fd29d3596..e72f4b181 100644
--- a/tasks.c
+++ b/tasks.c
@@ -33,8 +33,6 @@
  * task.h is included from an application file. */
 #define MPU_WRAPPERS_INCLUDED_FROM_API_FILE
 
-#define DEBUG_UNIT    FREERTOS_TASKS
-
 /* FreeRTOS includes. */
 #include "FreeRTOS.h"
 #include "task.h"