Fix nasa#821, add accessor functions for version strings

Adds 3 simple API calls:

const char *OS_GetVersion(void);
const char *OS_GetVersionCodeName(void);
const char *OS_GetVersionDescription(void);

These directly return the values of string macros in osapi-version.h.

The accessor function should be the preferred way to get the OSAL version
string (vs. using macro directly) as it is evaluated at OSAL library
compile time, rather than application compile time, and thus will
remain correct in the event that OSAL is relinked without recompiling
the application.

CMakeLists.txt

@@ -249,6 +249,7 @@ set(OSAL_SRCLIST
     src/os/shared/src/osapi-task.c
     src/os/shared/src/osapi-timebase.c
     src/os/shared/src/osapi-time.c
+    src/os/shared/src/osapi-version.c
 )
 
 if (OSAL_CONFIG_DEBUG_PRINTF)

src/os/inc/osapi-version.h

@@ -56,13 +56,18 @@
  */
 #define OS_VERSION OS_BUILD_BASELINE "+dev" OS_STR(OS_BUILD_NUMBER)
 
+/*! @brief Version code name
+ * All modular components which are tested/validated together should share the same code name
+ */
+#define OS_VERSION_CODENAME  "Bootes"
+
 /*! @brief Development Build Version String.
  * @details Reports the current development build's baseline, number, and name. Also includes a note about the latest
  * official version. @n See @ref cfsversions for format differences between development and release versions.
  */
 #define OS_VERSION_STRING                                                          \
     " OSAL Development Build\n"                                                    \
-    " " OS_VERSION " (Codename: Bootes)\n"  /* Codename for current development */ \
+    " " OS_VERSION " (Codename: " OS_VERSION_CODENAME ")\n"  /* Codename for current development */ \
     " Latest Official Version: osal v5.0.0" /* For full support please use official release version */
 
 /*! @brief Combines the revision components into a single value
@@ -72,6 +77,55 @@ OSAL 4.1 is present.
  */
 #define OSAL_API_VERSION ((OS_MAJOR_VERSION * 10000) + (OS_MINOR_VERSION * 100) + OS_REVISION)
 
+
+/*
+ * Functions to get OSAL version info
+ *
+ * It is preferable to use the functions below to retrieve the OSAL version
+ * at runtime, because if applications reference the macros above directly, the
+ * macro will only get evaluated when the _application_ is built.
+ *
+ * When using the functions below, the version gets evaluated when the OSAL library
+ * is built, and therefore if the OSAL library is re-linked without rebuilding the
+ * application itself, the version will still be correct.
+ */
+
+
+/**
+ * Gets the OSAL version/baseline ID.
+ *
+ * This returns the content of the #OS_VERSION macro defined above, and is specifically
+ * just the baseline and development build ID (if applicable), without any extra info.
+ *
+ * \returns Basic version identifier.  This is a fixed value string and is never NULL.
+ */
+const char *OS_GetVersion(void);
+
+/**
+ * Gets the OSAL version code name
+ *
+ * All NASA CFE/CFS components (including CFE framework, OSAL and PSP) that work
+ * together will share the same code name.
+ *
+ * \returns OSAL code name.  This is a fixed value string and is never NULL.
+ */
+const char *OS_GetVersionCodeName(void);
+
+/**
+ * Gets the complete OSAL version description
+ *
+ * This returns the content of the #OS_VERSION_STRING macro defined above, and is
+ * an extension of the basic information reported by OS_GetVersion().
+ *
+ * In addition to the basic information, this also includes descriptive text indicating
+ * the codename for cross-module compatiblity, whether this is an offical release or
+ * development build, and if it is development build, it indicates official release
+ * baseline that it was based off of.
+ *
+ * \returns Extended version description string. This is a fixed value string and is never NULL.
+ */
+const char *OS_GetVersionDescription(void);
+
 #endif /* OSAPI_VERSION_H */
 
 /************************/

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

@@ -0,0 +1,72 @@
+/*
+ *  NASA Docket No. GSC-18,370-1, and identified as "Operating System Abstraction Layer"
+ *
+ *  Copyright (c) 2019 United States Government as represented by
+ *  the Administrator of the National Aeronautics and Space Administration.
+ *  All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+/**
+ * \file     osapi-version.c
+ * \ingroup  shared
+ * \author   joseph.p.hickey@nasa.gov
+ *
+ *  Defines functions that return version information strings
+ */
+
+/****************************************************************************************
+                                    INCLUDE FILES
+ ***************************************************************************************/
+#include <osapi-version.h>
+
+/*----------------------------------------------------------------
+ *
+ * Function: OS_GetVersion
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+const char *OS_GetVersion(void)
+{
+    return OS_VERSION;
+}
+
+/*----------------------------------------------------------------
+ *
+ * Function: OS_GetVersionCodeName
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+const char *OS_GetVersionCodeName(void)
+{
+    return OS_VERSION_CODENAME;
+}
+
+/*----------------------------------------------------------------
+ *
+ * Function: OS_GetVersionDescription
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+const char *OS_GetVersionDescription(void)
+{
+    return OS_VERSION_STRING;
+}
+

src/unit-test-coverage/shared/CMakeLists.txt

@@ -23,6 +23,7 @@ set(MODULE_LIST
     task
     timebase
     time
+    version
 )
 
 set(SHARED_COVERAGE_LINK_LIST

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

@@ -0,0 +1,118 @@
+/*
+ *  NASA Docket No. GSC-18,370-1, and identified as "Operating System Abstraction Layer"
+ *
+ *  Copyright (c) 2019 United States Government as represented by
+ *  the Administrator of the National Aeronautics and Space Administration.
+ *  All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+/**
+ * \file     coveragetest-version.c
+ * \ingroup  shared
+ * \author   joseph.p.hickey@nasa.gov
+ *
+ * Exercise the "GetVersion" functions.  These functions do not have any actual
+ * logic, they just directly return fixed strings, but they should be called as
+ * part of unit test for coverage reasons.
+ *
+ * The strings are free-form and no specific format is checked, the only real
+ * requirement is that they are not NULL.
+ */
+#include "os-shared-coveragetest.h"
+
+#include "osapi-version.h"
+
+/*
+**********************************************************************************
+**          PUBLIC API FUNCTIONS
+**********************************************************************************
+*/
+
+void Test_OS_GetVersion(void)
+{
+    /*
+     * Test Case For:
+     * const char *OS_GetVersion(void)
+     */
+    const char *Result;
+
+    Result = OS_GetVersion();
+    UtAssert_NOT_NULL(Result);
+
+    /*
+     * Display the version description string, just for informational purposes
+     */
+    UtPrintf("OS_GetVersion() Returned: %s\n", Result);
+}
+
+void Test_OS_GetVersionCodeName(void)
+{
+    /*
+     * Test Case For:
+     * const char *OS_GetVersionCodeName(void)
+     */
+    const char *Result;
+
+    Result = OS_GetVersionCodeName();
+    UtAssert_NOT_NULL(Result);
+
+    /*
+     * Display the code name string, just for informational purposes
+     */
+    UtPrintf("OS_GetVersionCodeName() Returned: %s\n", Result);
+}
+
+void Test_OS_GetVersionDescription(void)
+{
+    /*
+     * Test Case For:
+     * const char *OS_GetVersionDescription(void)
+     */
+    const char *Result;
+
+    Result = OS_GetVersionDescription();
+    UtAssert_NOT_NULL(Result);
+
+    /*
+     * Display the version description string, just for informational purposes
+     */
+    UtPrintf("OS_GetVersionDescription() Returned: %s\n", Result);
+}
+
+
+/* Osapi_Test_Setup
+ *
+ * Purpose:
+ *   Called by the unit test tool to set up the app prior to each test
+ */
+void Osapi_Test_Setup(void) {}
+
+/*
+ * Osapi_Test_Teardown
+ *
+ * Purpose:
+ *   Called by the unit test tool to tear down the app after each test
+ */
+void Osapi_Test_Teardown(void) {}
+
+/*
+ * Register the test cases to execute with the unit test tool
+ */
+void UtTest_Setup(void)
+{
+    ADD_TEST(OS_GetVersion);
+    ADD_TEST(OS_GetVersionCodeName);
+    ADD_TEST(OS_GetVersionDescription);
+}