Merge pull request nasa#824 from 'jphickey/fix-821-version-strings'

Fix nasa#821, add accessor functions for version strings

Fix format in `osapi-utstub-version.c`

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

@@ -27,6 +27,8 @@
 #ifndef OSAPI_VERSION_H
 #define OSAPI_VERSION_H
 
+#include "common_types.h"
+
 /*
  * Development Build Macro Definitions
  */
@@ -38,11 +40,15 @@
  */
 #define OS_MAJOR_VERSION 5 /*!< @brief ONLY APPLY for OFFICIAL releases. Major version number. */
 #define OS_MINOR_VERSION 0 /*!< @brief ONLY APPLY for OFFICIAL releases. Minor version number. */
-#define OS_REVISION                                                                                                   \
-    99 /*!< @brief ONLY APPLY for OFFICIAL releases. Revision version number. A value of "99" indicates an unreleased \
-          development version.  */
+#define OS_REVISION      0 /*!< @brief ONLY APPLY for OFFICIAL releases. Revision number.      */
 
-#define OS_MISSION_REV 0 /*!< @brief ONLY USED by MISSION Implementations. Mission revision */
+/*!
+ * @brief Mission revision.
+ *
+ * Set to 0 on OFFIFICIAL releases, and set to 255 (0xFF) on development versions.
+ * Values 1-254 are reserved for mission use to denote patches/customizations as needed.
+ */
+#define OS_MISSION_REV 0xFF
 
 /*
  * Tools to construct version string
@@ -56,14 +62,19 @@
  */
 #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 */ \
-    " Latest Official Version: osal v5.0.0" /* For full support please use official release version */
+#define OS_VERSION_STRING                                                                          \
+    " OSAL Development Build\n"                                                                    \
+    " " 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
  * @details Applications can check against this number @n
@@ -72,6 +83,73 @@ 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 as a string
+ *
+ * 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_GetVersionString(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);
+
+/**
+ * \brief Obtain the OSAL numeric version number
+ *
+ * This retrieves the numeric OSAL version identifier as an array of 4 uint8 values.
+ *
+ * The array of numeric values is in order of precedence:
+ *  [0] = Major Number
+ *  [1] = Minor Number
+ *  [2] = Revision Number
+ *  [3] = Mission Revision
+ *
+ * The "Mission Revision" (last output) also indicates whether this is an
+ * official release, a patched release, or a development version.
+ *  0 indicates an official release
+ *  1-254 local patch level (reserved for mission use)
+ *  255 indicates a development build
+ *
+ * \param[out] VersionNumbers  A fixed-size array to be filled with the version numbers
+ */
+void OS_GetVersionNumber(uint8 VersionNumbers[4]);
+
+/**
+ * \brief Obtain the OSAL library numeric build number
+ *
+ * The build number is a monotonically increasing number that (coarsely)
+ * reflects the number of commits/changes that have been merged since the
+ * epoch release.  During development cycles this number should increase
+ * after each subsequent merge/modification.
+ *
+ * Like other version information, this is a fixed number assigned at compile time.
+ *
+ * \returns The OSAL library build number
+ */
+uint32 OS_GetBuildNumber(void);
+
 #endif /* OSAPI_VERSION_H */
 
 /************************/

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

@@ -0,0 +1,87 @@
+/*
+ *  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
+ */
+
+/****************************************************************************************
+                                    INCLUDE FILES
+ ***************************************************************************************/
+#include <osapi-version.h>
+
+/*----------------------------------------------------------------
+ *
+ * Function: OS_GetVersionString
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+const char *OS_GetVersionString(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_GetVersionNumber
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+void OS_GetVersionNumber(uint8 VersionNumbers[4])
+{
+    VersionNumbers[0] = OS_MAJOR_VERSION;
+    VersionNumbers[1] = OS_MINOR_VERSION;
+    VersionNumbers[2] = OS_REVISION;
+    VersionNumbers[3] = OS_MISSION_REV;
+}
+
+/*----------------------------------------------------------------
+ *
+ * Function: OS_GetBuildNumber
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+uint32 OS_GetBuildNumber(void)
+{
+    return OS_BUILD_NUMBER;
+}

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,143 @@
+/*
+ *  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_GetVersionString(void)
+{
+    /*
+     * Test Case For:
+     * const char *OS_GetVersionString(void)
+     */
+    const char *Result;
+
+    Result = OS_GetVersionString();
+    UtAssert_NOT_NULL(Result);
+
+    /*
+     * Display the version description string, just for informational purposes
+     */
+    UtPrintf("OS_GetVersionString() 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_GetVersionNumber(void)
+{
+    /*
+     * Test Case For:
+     * void OS_GetVersionNumber(uint8 VersionNumbers[4])
+     */
+    uint8 VersionNum[4] = {0};
+
+    OS_GetVersionNumber(VersionNum);
+
+    /*
+     * This should output the same info as the version macros
+     */
+    UtAssert_INT32_EQ(VersionNum[0], OS_MAJOR_VERSION);
+    UtAssert_INT32_EQ(VersionNum[1], OS_MINOR_VERSION);
+    UtAssert_INT32_EQ(VersionNum[2], OS_REVISION);
+    UtAssert_INT32_EQ(VersionNum[3], OS_MISSION_REV);
+
+    /*
+     * Display the version number, just for informational purposes
+     */
+    UtPrintf("OS_GetVersionNumber() Returned: %u.%u.%u.%u\n", (unsigned int)VersionNum[0], (unsigned int)VersionNum[1],
+             (unsigned int)VersionNum[2], (unsigned int)VersionNum[3]);
+}
+
+void Test_OS_GetBuildNumber(void)
+{
+    /*
+     * Test Case For:
+     * uint32 OS_GetBuildNumber(void)
+     */
+    uint32 Result;
+
+    Result = OS_GetBuildNumber();
+    UtAssert_NONZERO(Result);
+
+    /*
+     * Display the build number, just for informational purposes
+     */
+    UtPrintf("Test_OS_GetBuildNumber() Returned: %lu\n", (unsigned long)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_GetVersionString);
+    ADD_TEST(OS_GetVersionCodeName);
+    ADD_TEST(OS_GetVersionNumber);
+    ADD_TEST(OS_GetBuildNumber);
+}

src/ut-stubs/CMakeLists.txt

@@ -35,6 +35,7 @@ add_library(ut_osapi_stubs STATIC
     osapi-utstub-task.c
     osapi-utstub-time.c
     osapi-utstub-timebase.c
+    osapi-utstub-version.c
 )
 
 # Some of the internal API definitions in stubs are based on