Merge pull request #948 from jphickey/fix-944-osapi-teardown

Fix #944, add OS_API_Teardown

src/os/inc/osapi-common.h

@@ -140,6 +140,33 @@ void OS_Application_Run(void);
  */
 int32 OS_API_Init(void);
 
+/*-------------------------------------------------------------------------------------*/
+/**
+ * @brief Teardown/de-initialization of OSAL API
+ *
+ * This is the inverse of OS_API_Init().  It will release all OS resources and
+ * return the system to a state similar to what it was prior to invoking
+ * OS_API_Init() initially.
+ *
+ * Normally for embedded applications, the OSAL is initialized after boot and will remain
+ * initialized in memory until the processor is rebooted.  However for testing and
+ * developement purposes, it is potentially useful to reset back to initial conditions.
+ *
+ * For testing purposes, this API is designed/intended to be compatible with the
+ * UtTest_AddTeardown() routine provided by the UT-Assert subsystem.
+ *
+ * @note This is a "best-effort" routine and it may not always be possible/guaranteed
+ * to recover all resources, particularly in the case of off-nominal conditions, or if
+ * a resource is used outside of OSAL.
+ *
+ * For example, while this will attempt to unload all dynamically-loaded modules, doing
+ * so may not be possible and/or may induce undefined behavior if resources are in use by
+ * tasks/functions outside of OSAL.
+ *
+ * @return None
+ */
+void OS_API_Teardown(void);
+
 /*-------------------------------------------------------------------------------------*/
 /**
  * @brief Background thread implementation - waits forever for events to occur.

src/os/shared/src/osapi-common.c

@@ -246,6 +246,28 @@ int32 OS_API_Init(void)
     return (return_code);
 } /* end OS_API_Init */
 
+/*----------------------------------------------------------------
+ *
+ * Function: OS_API_Teardown
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+void OS_API_Teardown(void)
+{
+    /*
+     * This should delete any remaining user-created objects/tasks
+     */
+    OS_DeleteAllObjects();
+
+    /*
+     * This should cause the "internal" objects (e.g. console utility task)
+     * to exit, and will prevent any new objects from being created.
+     */
+    OS_ApplicationShutdown(true);
+}
+
 /*----------------------------------------------------------------
  *
  * Function: OS_RegisterEventHandler

src/tests/bin-sem-flush-test/bin-sem-flush-test.c

@@ -177,6 +177,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/bin-sem-test/bin-sem-test.c

@@ -186,6 +186,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/bin-sem-timeout-test/bin-sem-timeout-test.c

@@ -181,6 +181,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/count-sem-test/count-sem-test.c

@@ -151,6 +151,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/file-api-test/file-api-test.c

@@ -57,6 +57,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * This test case requires a fixed virtual dir for one test case.
      * Just map /test to a dir of the same name, relative to current dir.

src/tests/file-sys-add-fixed-map-api-test/file-sys-add-fixed-map-api-test.c

@@ -96,6 +96,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/idmap-api-test/idmap-api-test.c

@@ -348,6 +348,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/mutex-test/mutex-test.c

@@ -217,6 +217,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/network-api-test/network-api-test.c

@@ -658,6 +658,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/osal-core-test/osal-core-test.c

@@ -96,6 +96,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     UtTest_Add(TestTasks, NULL, NULL, "TASK");
     UtTest_Add(TestQueues, NULL, NULL, "MSGQ");
     UtTest_Add(TestBinaries, NULL, NULL, "BSEM");

src/tests/queue-test/queue-test.c

@@ -247,6 +247,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/select-test/select-test.c

@@ -596,6 +596,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/sem-speed-test/sem-speed-test.c

@@ -150,6 +150,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/shell-test/shell-test.c

@@ -101,6 +101,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/symbol-api-test/symbol-api-test.c

@@ -112,6 +112,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/time-base-api-test/time-base-api-test.c

@@ -264,6 +264,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/timer-add-api-test/timer-add-api-test.c

@@ -199,6 +199,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the test setup and check routines in UT assert
      */

src/tests/timer-test/timer-test.c

@@ -74,6 +74,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * Register the timer test setup and check routines in UT assert
      */

src/unit-test-coverage/shared/src/coveragetest-common.c

@@ -131,6 +131,18 @@ void Test_OS_API_Init(void)
     UT_ResetState(UT_KEY(OS_TaskAPI_Init));
 }
 
+void Test_OS_API_Teardown(void)
+{
+    /*
+     * Test Case For:
+     * void OS_API_Teardown(void);
+     */
+
+    /* Just need to call the API for coverage; there are no conditionals
+     * and the internal functions are each tested separately */
+    OS_API_Teardown();
+}
+
 void Test_OS_ApplicationExit(void)
 {
     /*
@@ -330,4 +342,5 @@ void UtTest_Setup(void)
     ADD_TEST(OS_IdleLoopAndShutdown);
     ADD_TEST(OS_ApplicationExit);
     ADD_TEST(OS_NotifyEvent);
+    ADD_TEST(OS_API_Teardown);
 }

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

@@ -188,6 +188,9 @@ void UT_os_init_task_get_info_test()
 
 void UtTest_Setup(void)
 {
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     UtTest_Add(UT_os_apiinit_test, NULL, NULL, "OS_API_Init");
 
     UtTest_Add(UT_os_printf_test, NULL, NULL, "OS_printf");

src/unit-tests/osfile-test/ut_osfile_test.c

@@ -132,6 +132,9 @@ void UT_os_init_file_misc()
 
 void UtTest_Setup(void)
 {
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     UT_os_initfs_test();
 
     if (UT_os_setup_fs() == OS_SUCCESS)

src/unit-tests/osfilesys-test/ut_osfilesys_test.c

@@ -121,6 +121,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     UT_os_init_fs_misc();
 
     UtTest_Add(UT_os_makefs_test, NULL, NULL, "OS_mkfs");

src/unit-tests/osloader-test/ut_osloader_test.c

@@ -67,6 +67,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     /*
      * This test needs to load the modules from the filesystem, so
      * there must be a virtual path corresponding to the path where

src/unit-tests/osnetwork-test/ut_osnetwork_test.c

@@ -65,6 +65,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     UtTest_Add(UT_os_networkgetid_test, NULL, NULL, "OS_NetworkGetID");
     UtTest_Add(UT_os_networkgethostname_test, NULL, NULL, "OS_NetworkGetHostName");
 }

src/unit-tests/ostimer-test/ut_ostimer_test.c

@@ -193,6 +193,9 @@ void UtTest_Setup(void)
         UtAssert_Abort("OS_API_Init() failed");
     }
 
+    /* the test should call OS_API_Teardown() before exiting */
+    UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
+
     UT_os_init_timer_misc();
 
     UtTest_Add(UT_os_timercreate_test, UT_os_setup_timercreate_test, NULL, "OS_TimerCreate");