Merge pull request nasa#996 from nasa/integration-candidate

osal Integration candidate: 2021-05-11

.github/workflows/static-analysis.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Run bundle cppcheck
         if: ${{matrix.cppcheck =='all'}}
-        run: cppcheck --force --inline-suppr --quiet . 2> ${{matrix.cppcheck}}_cppcheck_err.txt
+        run: cppcheck --force --inline-suppr . 2> ${{matrix.cppcheck}}_cppcheck_err.txt
 
         # Run strict static analysis for embedded portions of osal
       - name: osal strict cppcheck

README.md

@@ -11,6 +11,16 @@ The autogenerated OSAL user's guide can be viewed at <https://github.com/nasa/cF
 
 ## Version History
 
+### Development Build: v5.1.0-rc1+dev434
+
+- Updates the configuration guide to reflect cmake build system and the currently provided set of OS/BSP layers. Removes obsolete items from guide.
+- Converts UtAssert API documentation to doxygen and corrects stale and incorrect references.
+- Clarifies use of the stack_size parameter, and that it should not be 0.
+- Ensures consistency between the return values generated by each OSAL API and the doxygen documentation.
+- Fixes missing or incorrect explicitly-returned status code in the coverage tests.
+- Corrects one argument name mismatch in QueueCreate where it was prototyped as "data_size" but implemented as "max_size".
+- See <https://github.com/nasa/osal/pull/996> and <https://github.com/nasa/cfs/pull/256>
+
 ### Development Build: v5.1.0-rc1+dev417
 
 - Fixes infinite loop  in `UtPrintx()`. Adds the data's memory address to output. Note, UtPrintf displays the the file/line of the `UtPrintx` function, **not the actual test location**; it is better to call `UT_BSP_DoText` directly.

src/bsp/generic-linux/src/bsp_start.c

@@ -49,8 +49,10 @@ OS_BSP_GenericLinuxGlobalData_t OS_BSP_GenericLinuxGlobal;
    --------------------------------------------------------- */
 void OS_BSP_Initialize(void)
 {
-    FILE *fp;
-    char  buffer[32];
+    FILE *              fp;
+    char                buffer[32];
+    pthread_mutexattr_t mutex_attr;
+    int                 status;
 
     /*
      * If not running as root, check /proc/sys/fs/mqueue/msg_max
@@ -76,6 +78,53 @@ void OS_BSP_Initialize(void)
             fclose(fp);
         }
     }
+
+    /* Initialize the low level access mutex (w/priority inheritance) */
+    status = pthread_mutexattr_init(&mutex_attr);
+    if (status < 0)
+    {
+        BSP_DEBUG("pthread_mutexattr_init: %s\n", strerror(status));
+    }
+    status = pthread_mutexattr_setprotocol(&mutex_attr, PTHREAD_PRIO_INHERIT);
+    if (status < 0)
+    {
+        BSP_DEBUG("pthread_mutexattr_setprotocol: %s\n", strerror(status));
+    }
+    status = pthread_mutex_init(&OS_BSP_GenericLinuxGlobal.AccessMutex, &mutex_attr);
+    if (status < 0)
+    {
+        BSP_DEBUG("pthread_mutex_init: %s\n", strerror(status));
+    }
+}
+
+/*----------------------------------------------------------------
+   OS_BSP_Lock_Impl
+   See full description in header
+ ------------------------------------------------------------------*/
+void OS_BSP_Lock_Impl(void)
+{
+    int status;
+
+    status = pthread_mutex_lock(&OS_BSP_GenericLinuxGlobal.AccessMutex);
+    if (status < 0)
+    {
+        BSP_DEBUG("pthread_mutex_lock: %s\n", strerror(status));
+    }
+}
+
+/*----------------------------------------------------------------
+   OS_BSP_Unlock_Impl
+   See full description in header
+ ------------------------------------------------------------------*/
+void OS_BSP_Unlock_Impl(void)
+{
+    int status;
+
+    status = pthread_mutex_unlock(&OS_BSP_GenericLinuxGlobal.AccessMutex);
+    if (status < 0)
+    {
+        BSP_DEBUG("pthread_mutex_unlock: %s\n", strerror(status));
+    }
 }
 
 /* ---------------------------------------------------------
@@ -166,7 +215,7 @@ int main(int argc, char *argv[])
     }
 
     /*
-     * Auto-Create any missing FS_BASED mount points specified in OS_VolumeTable
+     * Perform any other BSP-specific initialization
      */
     OS_BSP_Initialize();
 

src/bsp/generic-linux/src/generic_linux_bsp_internal.h

@@ -33,12 +33,15 @@
 #include "osapi-error.h"
 #include "bsp-impl.h"
 
+#include <pthread.h>
+
 /*
 ** BSP types
 */
 typedef struct
 {
-    bool EnableTermControl; /**< Will be set "true" when invoked from a TTY device, false otherwise */
+    bool            EnableTermControl; /**< Will be set "true" when invoked from a TTY device, false otherwise */
+    pthread_mutex_t AccessMutex;
 } OS_BSP_GenericLinuxGlobalData_t;
 
 /*

src/bsp/generic-vxworks/src/bsp_start.c

@@ -30,9 +30,44 @@
 */
 #include <stdlib.h>
 #include <string.h>
+#include <errno.h>
 
 #include "generic_vxworks_bsp_internal.h"
 
+OS_BSP_GenericVxWorksGlobalData_t OS_BSP_GenericVxWorksGlobal;
+
+/* ---------------------------------------------------------
+    OS_BSP_Lock_Impl()
+
+     Helper function to get exclusive access to BSP
+   --------------------------------------------------------- */
+void OS_BSP_Lock_Impl(void)
+{
+    int status;
+
+    status = semTake(OS_BSP_GenericVxWorksGlobal.AccessMutex, WAIT_FOREVER);
+    if (status != OK)
+    {
+        BSP_DEBUG("semTake: errno=%d\n", errno);
+    }
+}
+
+/* ---------------------------------------------------------
+    OS_BSP_Unlock_Impl()
+
+     Helper function to release exclusive access to BSP
+   --------------------------------------------------------- */
+void OS_BSP_Unlock_Impl(void)
+{
+    int status;
+
+    status = semGive(OS_BSP_GenericVxWorksGlobal.AccessMutex);
+    if (status != OK)
+    {
+        BSP_DEBUG("semGive: errno=%d\n", errno);
+    }
+}
+
 /* ---------------------------------------------------------
     OS_BSP_Shutdown_Impl()
 
@@ -63,6 +98,18 @@ int OS_BSPMain(void)
      * Initially clear the global object (this contains return code)
      */
     memset(&OS_BSP_Global, 0, sizeof(OS_BSP_Global));
+    memset(&OS_BSP_GenericVxWorksGlobal, 0, sizeof(OS_BSP_GenericVxWorksGlobal));
+
+    /*
+     * Initialize the low level access sem
+     */
+    OS_BSP_GenericVxWorksGlobal.AccessMutex =
+        semMInitialize(OS_BSP_GenericVxWorksGlobal.AccessMutexMem, SEM_Q_PRIORITY | SEM_INVERSION_SAFE);
+
+    if (OS_BSP_GenericVxWorksGlobal.AccessMutex == (SEM_ID)0)
+    {
+        BSP_DEBUG("semMInitalize: errno=%d\n", errno);
+    }
 
     /*
      * Call application specific entry point.

src/bsp/generic-vxworks/src/generic_vxworks_bsp_internal.h

@@ -33,4 +33,21 @@
 */
 #include "bsp-impl.h"
 
+#include <semLib.h>
+
+/*
+** BSP types
+*/
+typedef struct
+{
+    SEM_ID AccessMutex;
+    VX_MUTEX_SEMAPHORE(AccessMutexMem);
+
+} OS_BSP_GenericVxWorksGlobalData_t;
+
+/*
+ * Global Data object
+ */
+extern OS_BSP_GenericVxWorksGlobalData_t OS_BSP_GenericVxWorksGlobal;
+
 #endif /* GENERIC_VXWORKS_BSP_INTERNAL_H */

src/bsp/pc-rtems/src/bsp_start.c

@@ -169,6 +169,17 @@ void OS_BSP_Setup(void)
         }
     }
 
+    /*
+     * Initialize the low level access sem
+     */
+    status = rtems_semaphore_create(rtems_build_name('B', 'S', 'P', '\0'), 1,
+                                    RTEMS_PRIORITY | RTEMS_BINARY_SEMAPHORE | RTEMS_INHERIT_PRIORITY, 0,
+                                    &OS_BSP_PcRtemsGlobal.AccessMutex);
+    if (status != RTEMS_SUCCESSFUL)
+    {
+        BSP_DEBUG("rtems_semaphore_create: %s\n", rtems_status_text(status));
+    }
+
     /*
     ** Create the RTEMS Root file system
     */
@@ -248,6 +259,34 @@ void OS_BSP_Setup(void)
     printf("\n\n");
 }
 
+/*----------------------------------------------------------------
+   OS_BSP_Lock_Impl
+   See full description in header
+ ------------------------------------------------------------------*/
+void OS_BSP_Lock_Impl(void)
+{
+    rtems_status_code status;
+    status = rtems_semaphore_obtain(OS_BSP_PcRtemsGlobal.AccessMutex, RTEMS_WAIT, RTEMS_NO_TIMEOUT);
+    if (status != RTEMS_SUCCESSFUL)
+    {
+        BSP_DEBUG("rtems_semaphore_obtain: %s\n", rtems_status_text(status));
+    }
+}
+
+/*----------------------------------------------------------------
+   OS_BSP_Unlock_Impl
+   See full description in header
+ ------------------------------------------------------------------*/
+void OS_BSP_Unlock_Impl(void)
+{
+    rtems_status_code status;
+    status = rtems_semaphore_release(OS_BSP_PcRtemsGlobal.AccessMutex);
+    if (status != RTEMS_SUCCESSFUL)
+    {
+        BSP_DEBUG("rtems_semaphore_release: %s\n", rtems_status_text(status));
+    }
+}
+
 /* ---------------------------------------------------------
     OS_BSP_GetReturnStatus()
 

src/bsp/pc-rtems/src/pcrtems_bsp_internal.h

@@ -33,6 +33,8 @@
 */
 #include "bsp-impl.h"
 
+#include <rtems.h>
+
 /*
  * BSP compile-time tuning
  */
@@ -64,8 +66,9 @@
 */
 typedef struct
 {
-    char UserArgBuffer[RTEMS_MAX_CMDLINE];
-    bool BatchMode;
+    char     UserArgBuffer[RTEMS_MAX_CMDLINE];
+    bool     BatchMode;
+    rtems_id AccessMutex;
 } OS_BSP_PcRtemsGlobalData_t;
 
 /*

src/bsp/shared/inc/bsp-impl.h

@@ -108,6 +108,28 @@ extern OS_BSP_GlobalData_t OS_BSP_Global;
 /* INTERNAL BSP IMPLEMENTATION FUNCTIONS                            */
 /********************************************************************/
 
+/*----------------------------------------------------------------
+   Function: OS_BSP_Lock_Impl
+
+    Purpose: Get exclusive access to a BSP-provided service or object
+
+             Useful in conjuction with console output functions to avoid strings
+             from multiple tasks getting mixed together in the final output.
+
+ ------------------------------------------------------------------*/
+void OS_BSP_Lock_Impl(void);
+
+/*----------------------------------------------------------------
+   Function: OS_BSP_Unlock_Impl
+
+    Purpose: Release exclusive access to a BSP-provided service or object
+
+             This must be called after a call to OS_BSP_Lock_Impl() once
+             access is complete, to allow other tasks to use the resource.
+
+ ------------------------------------------------------------------*/
+void OS_BSP_Unlock_Impl(void);
+
 /*----------------------------------------------------------------
    Function: OS_BSP_ConsoleOutput_Impl
 

src/os/inc/osapi-clock.h

@@ -83,6 +83,7 @@ enum
  * @param[out]  time_struct An OS_time_t that will be set to the current time
  *
  * @return Get local time status, see @ref OSReturnCodes
+ * @retval #OS_INVALID_POINTER if time_struct is null
  */
 int32 OS_GetLocalTime(OS_time_t *time_struct);
 
@@ -97,6 +98,7 @@ int32 OS_GetLocalTime(OS_time_t *time_struct);
  * @param[in]  time_struct An OS_time_t containing the current time
  *
  * @return Set local time status, see @ref OSReturnCodes
+ * @retval #OS_INVALID_POINTER if time_struct is null
  */
 int32 OS_SetLocalTime(const OS_time_t *time_struct);
 

src/os/inc/osapi-common.h

@@ -162,8 +162,6 @@ int32 OS_API_Init(void);
  * 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);
 
@@ -234,6 +232,7 @@ void OS_ApplicationExit(int32 Status);
  * @return Execution status, see @ref OSReturnCodes.
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_ERROR   @copybrief OS_ERROR
+ * @retval #OS_INVALID_POINTER if handler is NULL
  */
 int32 OS_RegisterEventHandler(OS_EventHandler_t handler);
 

src/os/inc/osapi-dir.h

@@ -57,6 +57,7 @@ typedef struct
  * @param[in]  path      The directory to open
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_INVALID_POINTER if dir_id or path is NULL
  */
 int32 OS_DirectoryOpen(osal_id_t *dir_id, const char *path);
 
@@ -94,6 +95,7 @@ int32 OS_DirectoryRewind(osal_id_t dir_id);
  * @param[out] dirent    Buffer to store directory entry information
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_INVALID_POINTER if dirent argument is NULL
  */
 int32 OS_DirectoryRead(osal_id_t dir_id, os_dirent_t *dirent);
 

src/os/inc/osapi-error.h

@@ -117,6 +117,9 @@ typedef char os_err_name_t[OS_ERROR_NAME_LENGTH];
  * @param[out] err_name Buffer to store error string
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_SUCCESS if successfully converted to a string
+ * @retval #OS_INVALID_POINTER if err_name is NULL
+ * @retval #OS_ERROR if error could not be converted
  */
 int32 OS_GetErrorName(int32 error_num, os_err_name_t *err_name);
 /**@}*/