Fix #1024, check misc API return codes

Fix missing doxygen retvals

Note, other tests were OK, but depend on support being enabled and
supported by RTOS.  Script will report N/A items (due to no impl) as
missing.  Confirmed OS_HeapGetInfo OK on RTEMS.

For test cases where a function is invoked before OS_API_Init, only
check that the result is not success.  This will remain as "undocumented"
behavior - users should not call functions before init, because it is
not valid to do so.  A specific error code is not guaranteed here.

src/os/inc/osapi-heap.h

@@ -53,6 +53,7 @@ typedef struct
  * @param[out] heap_prop Storage buffer for heap info
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_INVALID_POINTER if the heap_prop argument is NULL
  */
 int32 OS_HeapGetInfo(OS_heap_prop_t *heap_prop);

src/os/inc/osapi-network.h

@@ -65,6 +65,7 @@ int32 OS_NetworkGetID(void);
  * @param[in]   name_len     Maximum length of host name buffer
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_ERR_INVALID_SIZE if the name_len is zero
  * @retval #OS_INVALID_POINTER if the host_name is NULL
  */

src/os/inc/osapi-shell.h

@@ -41,7 +41,7 @@
  * Takes a shell command in and writes the output of that command to the specified file
  * The output file must be opened previously with write access (OS_WRITE_ONLY or OS_READ_WRITE).
  *
- * @param[in] Cmd     Command to pass to shell
+ * @param[in] Cmd     Command to pass to shell @nonnull
  * @param[in] filedes File to send output to.
  *
  * @return Execution status, see @ref OSReturnCodes

src/unit-tests/inc/ut_os_support.h

@@ -73,6 +73,13 @@ static inline bool UtOsalRetVal(int32 Fn, int32 Exp, bool NotImplAllowed, UtAsse
     return UtAssertEx(Fn == Exp, casetype, File, Line, "%s (%d) == %s (%d)", FnTxt, (int)Fn, ExpTxt, (int)Exp);
 }
 
+static inline bool UtOsalNotSuccess(int32 Fn, UtAssert_CaseType_t casetype,
+                                const char *File, uint32 Line, const char *FnTxt)
+{
+    /* Check result is negative to support APIs that return nonzero on success (e.g. read/write) */
+    return UtAssertEx(Fn < 0, casetype, File, Line, "%s (%d) not successful", FnTxt, (int)Fn);
+}
+
 static inline bool UtManualInspectionWithStatus(int32 Fn, const char *File, uint32 Line, const char *FnTxt)
 {
     UtAssertEx(false, UTASSERT_CASETYPE_MIR, File, Line, "%s value=%d", FnTxt, (int)Fn);
@@ -107,6 +114,8 @@ static inline bool UtOsalImplemented(int32 Fn, const char *File, uint32 Line)
     UtOsalRetVal(Fn, OS_SUCCESS, false, UTASSERT_CASETYPE_FAILURE, __FILE__, __LINE__, #Fn, "OS_SUCCESS")
 #define UT_NOMINAL_OR_NOTIMPL(Fn) \
     UtOsalRetVal(Fn, OS_SUCCESS, true, UTASSERT_CASETYPE_FAILURE, __FILE__, __LINE__, #Fn, "OS_SUCCESS")
+#define UT_NOT_SUCCESS(Fn) \
+    UtOsalNotSuccess(Fn, UTASSERT_CASETYPE_FAILURE, __FILE__, __LINE__, #Fn)
 
 #define UT_MIR_STATUS(Fn) UtManualInspectionWithStatus(Fn, __FILE__, __LINE__, #Fn)
 #define UT_MIR_VOID(Fn)   Fn, UtAssertEx(false, UTASSERT_CASETYPE_MIR, __FILE__, __LINE__, "%s", #Fn)

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

@@ -98,10 +98,17 @@ void UT_os_apiinit_test()
     /*-----------------------------------------------------*/
     /* #1 Init-not-call-first */
 
-    UT_RETVAL(OS_QueueCreate(&qId, "Queue A", qDepth, qSize, qFlags), OS_ERROR);
-    UT_RETVAL(OS_BinSemCreate(&semIds[0], "BinSem 1", semInitValue, semOptions), OS_ERROR);
-    UT_RETVAL(OS_CountSemCreate(&semIds[1], "CountSem 1", semInitValue, semOptions), OS_ERROR);
-    UT_RETVAL(OS_MutSemCreate(&semIds[2], "MutexSem 1", semOptions), OS_ERROR);
+    /*
+     * Note that OS_API_Init() is supposed to be the first function invoked,
+     * calling any other OSAL API before this is technically undefined behavior.
+     * There is code to check for errors in this regard so this just tests that
+     * the result is _not_ success.  The specific status code if called before
+     * OS_API_Init is not documented.
+     */
+    UT_NOT_SUCCESS(OS_QueueCreate(&qId, "Queue A", qDepth, qSize, qFlags));
+    UT_NOT_SUCCESS(OS_BinSemCreate(&semIds[0], "BinSem 1", semInitValue, semOptions));
+    UT_NOT_SUCCESS(OS_CountSemCreate(&semIds[1], "CountSem 1", semInitValue, semOptions));
+    UT_NOT_SUCCESS(OS_MutSemCreate(&semIds[2], "MutexSem 1", semOptions));
 
     /*-----------------------------------------------------*/
     /* #2 Nominal */
@@ -418,23 +425,15 @@ void UT_os_heapgetinfo_test(void)
 {
     OS_heap_prop_t heapProp;
 
-    /*-----------------------------------------------------*/
-    /* API not implemented */
-
-    if (!UT_IMPL(OS_HeapGetInfo(&heapProp)))
-    {
-        return;
-    }
-
     /*-----------------------------------------------------*/
     /* #1 Null-pointer-arg */
 
     UT_RETVAL(OS_HeapGetInfo(NULL), OS_INVALID_POINTER);
 
     /*-----------------------------------------------------*/
-    /* #3 Nominal */
+    /* #3 Nominal (allows for not implemented) */
 
-    UT_NOMINAL(OS_HeapGetInfo(&heapProp));
+    UT_NOMINAL_OR_NOTIMPL(OS_HeapGetInfo(&heapProp));
 }
 
 /*================================================================================*

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

@@ -1394,11 +1394,6 @@ void UT_os_movefile_test()
 **--------------------------------------------------------------------------------*/
 void UT_os_outputtofile_test()
 {
-    /*-----------------------------------------------------*/
-    /* #1 Null-pointer-arg */
-
-    UT_RETVAL(OS_ShellOutputToFile(NULL, OS_OBJECT_ID_UNDEFINED), OS_INVALID_POINTER);
-
     /*-----------------------------------------------------*/
     /* #2 Invalid-file-desc-arg */
 
@@ -1411,7 +1406,12 @@ void UT_os_outputtofile_test()
     UT_os_sprintf(g_fNames[0], "%s/Output_Nominal.txt", g_mntName);
     if (UT_SETUP(OS_OpenCreate(&g_fDescs[0], g_fNames[0], OS_FILE_FLAG_CREATE | OS_FILE_FLAG_TRUNCATE, OS_READ_WRITE)))
     {
-        /* #4 Nominal - File-create failed */
+        /*-----------------------------------------------------*/
+        /* Null-pointer-arg */
+
+        UT_RETVAL(OS_ShellOutputToFile(NULL, g_fDescs[0]), OS_INVALID_POINTER);
+
+        /* Nominal */
         if (UT_NOMINAL_OR_NOTIMPL(OS_ShellOutputToFile("echo \"UT_os_outputtofile_test\"", g_fDescs[0])))
         {
             UT_RETVAL(OS_lseek(g_fDescs[0], 0, OS_SEEK_SET), 0);
@@ -1421,6 +1421,13 @@ void UT_os_outputtofile_test()
                 UtAssert_True(strstr(g_readBuff, "UT_os_outputtofile_test") != NULL,
                               "Output file contains UT_os_outputtofile_test");
             }
+
+            /*
+             * Executing a command name "false" should fail, either because it is not a known
+             * command, or if it is valid (e.g. a UNIX-like environment has /bin/false) the
+             * command always fails.
+             */
+            UT_RETVAL(OS_ShellOutputToFile("false", g_fDescs[0]), OS_ERROR);
         }
 
         /* Reset test environment */