Fix nasa#1021, resolve discrepancies between task API and unit tests

Ensures correlation between the unit-tests and documented return
values for the OSAL task API.

Also adds the following test cases:
- Call OS_TaskCreate with a NULL stack pointer
- Confirm OS_TaskDeleteHandler function was invoked
- Confirm OS_TaskDelay interval

src/os/inc/osapi-task.h

@@ -92,11 +92,11 @@ typedef osal_task((*osal_task_entry)(void)); /**< @brief For task entry point */
  * the system heap.
  *
  * @param[out]  task_id will be set to the non-zero ID of the newly-created resource
- * @param[in]   task_name the name of the new resource to create
- * @param[in]   function_pointer the entry point of the new task
+ * @param[in]   task_name the name of the new resource to create @nonnull
+ * @param[in]   function_pointer the entry point of the new task @nonnull
  * @param[in]   stack_pointer pointer to the stack for the task, or NULL
  *              to allocate a stack from the system memory heap
- * @param[in]   stack_size the size of the stack
+ * @param[in]   stack_size the size of the stack @nonzero
  * @param[in]   priority initial priority of the new task
  * @param[in]   flags initial options for the new task
  *
@@ -105,10 +105,10 @@ typedef osal_task((*osal_task_entry)(void)); /**< @brief For task entry point */
  * @retval #OS_INVALID_POINTER if any of the necessary pointers are NULL
  * @retval #OS_ERR_INVALID_SIZE if the stack_size argument is zero
  * @retval #OS_ERR_NAME_TOO_LONG name length including null terminator greater than #OS_MAX_API_NAME
- * @retval #OS_ERR_INVALID_PRIORITY if the priority is bad
+ * @retval #OS_ERR_INVALID_PRIORITY if the priority is bad @covtest
  * @retval #OS_ERR_NO_FREE_IDS if there can be no more tasks created
  * @retval #OS_ERR_NAME_TAKEN if the name specified is already used by a task
- * @retval #OS_ERROR if an unspecified/other error occurs
+ * @retval #OS_ERROR if an unspecified/other error occurs @covtest
  */
 int32 OS_TaskCreate(osal_id_t *task_id, const char *task_name, osal_task_entry function_pointer,
                     osal_stackptr_t stack_pointer, size_t stack_size, osal_priority_t priority, uint32 flags);
@@ -125,7 +125,7 @@ int32 OS_TaskCreate(osal_id_t *task_id, const char *task_name, osal_task_entry f
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_ERR_INVALID_ID if the ID given to it is invalid
- * @retval #OS_ERROR if the OS delete call fails
+ * @retval #OS_ERROR if the OS delete call fails @covtest
  */
 int32 OS_TaskDelete(osal_id_t task_id);
 
@@ -149,6 +149,7 @@ void OS_TaskExit(void);
  * @param[in]   function_pointer function to be called when task exits
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_ERR_INVALID_ID if the calling context is not an OSAL task
  */
 int32 OS_TaskInstallDeleteHandler(osal_task_entry function_pointer);
 
@@ -163,7 +164,7 @@ int32 OS_TaskInstallDeleteHandler(osal_task_entry function_pointer);
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
- * @retval #OS_ERROR if sleep fails or millisecond = 0
+ * @retval #OS_ERROR if an unspecified/other error occurs @covtest
  */
 int32 OS_TaskDelay(uint32 millisecond);
 
@@ -172,14 +173,13 @@ int32 OS_TaskDelay(uint32 millisecond);
  * @brief Sets the given task to a new priority
  *
  * @param[in] task_id        The object ID to operate on
- *
  * @param[in] new_priority   Set the new priority
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_ERR_INVALID_ID if the ID passed to it is invalid
- * @retval #OS_ERR_INVALID_PRIORITY if the priority is greater than the max allowed
- * @retval #OS_ERROR if the OS call to change the priority fails
+ * @retval #OS_ERR_INVALID_PRIORITY if the priority is greater than the max allowed @covtest
+ * @retval #OS_ERROR if an unspecified/other error occurs @covtest
  */
 int32 OS_TaskSetPriority(osal_id_t task_id, osal_priority_t new_priority);
 
@@ -200,7 +200,7 @@ osal_id_t OS_TaskGetId(void);
  * This function tries to find a task Id given the name of a task
  *
  * @param[out]  task_id will be set to the ID of the existing resource
- * @param[in]   task_name the name of the existing resource to find
+ * @param[in]   task_name the name of the existing resource to find @nonnull
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
@@ -219,7 +219,7 @@ int32 OS_TaskGetIdByName(osal_id_t *task_id, const char *task_name);
  * specified task.
  *
  * @param[in]   task_id The object ID to operate on
- * @param[out]  task_prop The property object buffer to fill
+ * @param[out]  task_prop The property object buffer to fill @nonnull
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
@@ -239,12 +239,12 @@ int32 OS_TaskGetInfo(osal_id_t task_id, OS_task_prop_t *task_prop);
  * but in some circumstances, such as exception handling, the OS may provide this information
  * directly to a BSP handler outside of the normal OSAL API.
  *
- * @param[out]  task_id         The buffer where the task id output is stored
+ * @param[out]  task_id         The buffer where the task id output is stored @nonnull
  * @param[in]   sysdata         Pointer to the system-provided identification data
  * @param[in]   sysdata_size    Size of the system-provided identification data
  *
  * @return Execution status, see @ref OSReturnCodes
- * @retval #OS_SUCCESS @copybrief OS_SUCCESS
+ * @retval #OS_SUCCESS @copybrief OS_SUCCESS @covtest
  * @retval #OS_INVALID_POINTER if a pointer argument is NULL
  */
 int32 OS_TaskFindIdBySystemData(osal_id_t *task_id, const void *sysdata, size_t sysdata_size);

src/unit-tests/oscore-test/ut_oscore_task_test.c

@@ -53,6 +53,7 @@ extern char  g_long_task_name[UT_OS_NAME_BUFF_SIZE];
 **--------------------------------------------------------------------------------*/
 
 uint32    g_task_result = 0;
+bool      g_task_handler_called;
 osal_id_t g_task_sync_sem;
 osal_id_t g_task_ids[UT_OS_TASK_LIST_LEN];
 osal_id_t g_task_get_id_result;
@@ -129,6 +130,13 @@ void UT_os_task_create_test()
                             sizeof(g_task_stacks[3]), OSAL_PRIORITY_C(UT_TASK_PRIORITY), 0),
               OS_INVALID_POINTER);
 
+    /*-----------------------------------------------------*/
+    /* Bad stack size */
+
+    UT_RETVAL(OS_TaskCreate(&g_task_ids[3], g_task_names[3], generic_test_task, OSAL_STACKPTR_C(&g_task_stacks[3]), 0,
+                            OSAL_PRIORITY_C(UT_TASK_PRIORITY), 0),
+              OS_ERR_INVALID_SIZE);
+
     /*-----------------------------------------------------*/
     /* #4 Name-too-long */
 
@@ -184,15 +192,22 @@ void UT_os_task_create_test()
     }
 
     /*-----------------------------------------------------*/
-    /* #9 Nominal */
+    /* Nominal, fixed stack */
 
     UT_NOMINAL(OS_TaskCreate(&g_task_ids[9], g_task_names[9], generic_test_task, OSAL_STACKPTR_C(&g_task_stacks[9]),
                              sizeof(g_task_stacks[9]), OSAL_PRIORITY_C(UT_TASK_PRIORITY), 0));
 
+    /*-----------------------------------------------------*/
+    /* Nominal, dynamic stack */
+
+    UT_NOMINAL(OS_TaskCreate(&g_task_ids[8], g_task_names[8], generic_test_task, NULL, sizeof(g_task_stacks[8]),
+                             OSAL_PRIORITY_C(UT_TASK_PRIORITY), 0));
+
     /* Delay to let child task run */
     OS_TaskDelay(200);
 
     /* Reset test environment */
+    UT_TEARDOWN(OS_TaskDelete(g_task_ids[8]));
     UT_TEARDOWN(OS_TaskDelete(g_task_ids[9]));
 }
 
@@ -235,6 +250,7 @@ void UT_os_task_delete_test()
 void delete_handler_callback(void)
 {
     UtPrintf("Task delete callback...\n");
+    g_task_handler_called = true;
 }
 
 /*--------------------------------------------------------------------------------*/
@@ -283,6 +299,8 @@ void UT_os_task_install_delete_handler_test(void)
     {
         OS_BinSemTake(g_task_sync_sem);
 
+        g_task_handler_called = false;
+
         if (UT_SETUP(OS_TaskCreate(&g_task_ids[2], g_task_names[2], delete_handler_test_task,
                                    OSAL_STACKPTR_C(&g_task_stacks[2]), sizeof(g_task_stacks[2]),
                                    OSAL_PRIORITY_C(UT_TASK_PRIORITY), 0)))
@@ -297,6 +315,7 @@ void UT_os_task_install_delete_handler_test(void)
 
             UtAssert_True(g_task_result == OS_SUCCESS, "OS_TaskInstallDeleteHandler() (%d) == OS_SUCCESS",
                           (int)g_task_result);
+            UtAssert_True(g_task_handler_called, "OS_TaskInstallDeleteHandler() callback invoked");
         }
 
         UT_TEARDOWN(OS_BinSemDelete(g_task_sync_sem));
@@ -374,10 +393,27 @@ void UT_os_task_exit_test(void)
 **--------------------------------------------------------------------------------*/
 void UT_os_task_delay_test()
 {
-    /*-----------------------------------------------------*/
-    /* #2 Nominal */
+    OS_time_t before_time;
+    OS_time_t after_time;
+    int64     elapsed;
 
+    /*-----------------------------------------------------*/
+    /* Nominal, 100ms delay */
+    UT_SETUP(OS_GetLocalTime(&before_time));
     UT_NOMINAL(OS_TaskDelay(100));
+    UT_SETUP(OS_GetLocalTime(&after_time));
+
+    elapsed = OS_TimeGetTotalMilliseconds(OS_TimeSubtract(after_time, before_time));
+    UtAssert_True(elapsed >= 100, "Elapsed time %ld msec, expected 100", (long)elapsed);
+
+    /*-----------------------------------------------------*/
+    /* Nominal, 250ms delay */
+    UT_SETUP(OS_GetLocalTime(&before_time));
+    UT_NOMINAL(OS_TaskDelay(250));
+    UT_SETUP(OS_GetLocalTime(&after_time));
+
+    elapsed = OS_TimeGetTotalMilliseconds(OS_TimeSubtract(after_time, before_time));
+    UtAssert_True(elapsed >= 250, "Elapsed time %ld msec, expected 250", (long)elapsed);
 }
 
 /*--------------------------------------------------------------------------------*
@@ -554,6 +590,28 @@ void UT_os_task_get_info_test()
     }
 }
 
+/*--------------------------------------------------------------------------------*
+** Syntax: OS_TaskFindIdBySystemData
+** Purpose: Finds the abstract OSAL task ID from the system ID data
+**--------------------------------------------------------------------------------*/
+void UT_os_task_getid_by_sysdata_test()
+{
+    uint8     sysdata;
+    osal_id_t task_id;
+
+    /*
+     * NOTE: OSAL does not provide a means to get the low level system ID data directly.
+     * This API is intended to aid in exception processing in a PSP/BSP, where the
+     * low level task information is obtained outside of OSAL in a platform-specific
+     * manner.
+     *
+     * As a result this cannot check for nominal conditions, only validate the error checking.
+     */
+    UT_RETVAL(OS_TaskFindIdBySystemData(NULL, &sysdata, sizeof(sysdata)), OS_INVALID_POINTER);
+    UT_RETVAL(OS_TaskFindIdBySystemData(&task_id, NULL, sizeof(sysdata)), OS_INVALID_POINTER);
+    UT_RETVAL(OS_TaskFindIdBySystemData(&task_id, &sysdata, 0), OS_INVALID_POINTER);
+}
+
 /*================================================================================*
 ** End of File: ut_oscore_task_test.c
 **================================================================================*/

src/unit-tests/oscore-test/ut_oscore_task_test.h

@@ -67,6 +67,7 @@ void UT_os_task_get_id_by_name_test(void);
 void UT_os_task_get_info_test(void);
 void UT_os_task_delay_test(void);
 void UT_os_task_get_id_test(void);
+void UT_os_task_getid_by_sysdata_test(void);
 
 /*--------------------------------------------------------------------------------*/
 

src/unit-tests/oscore-test/ut_oscore_test.c

@@ -243,6 +243,7 @@ void UtTest_Setup(void)
     UtTest_Add(UT_os_task_get_id_test, UT_os_init_task_get_id_test, NULL, "OS_TaskGetId");
     UtTest_Add(UT_os_task_get_id_by_name_test, UT_os_init_task_get_id_by_name_test, NULL, "OS_TaskGetIdByName");
     UtTest_Add(UT_os_task_get_info_test, UT_os_init_task_get_info_test, NULL, "OS_TaskGetInfo");
+    UtTest_Add(UT_os_task_getid_by_sysdata_test, UT_os_task_getid_by_sysdata_test, NULL, "OS_TaskFindIdBySystemData");
 
     UtTest_Add(UT_os_geterrorname_test, NULL, NULL, "OS_GetErrorName");