Merge pull request #289 from nasa/integration-candidate

psp Integration candidate: 2021-04-06

CMakeLists.txt

@@ -42,10 +42,13 @@ set(GENERATED_EXTERNS)
 set(GENERATED_KEYVALS)
 foreach(PSPMOD ${PSP_TARGET_MODULE_LIST})
     add_subdirectory(fsw/modules/${PSPMOD} ${PSPMOD}-${CFE_PSP_TARGETNAME}-impl)
-    list(APPEND GENERATED_EXTERNS "extern CFE_PSP_ModuleApi_t CFE_PSP_${PSPMOD}_API;\n")
+    list(APPEND GENERATED_EXTERNS "extern CFE_PSP_ModuleApi_t CFE_PSP_${PSPMOD}_API\;\n")
     list(APPEND GENERATED_KEYVALS "{ .Name = \"${PSPMOD}\", .Api = &CFE_PSP_${PSPMOD}_API },\n")
 endforeach()
 
+string(CONCAT GENERATED_EXTERNS ${GENERATED_EXTERNS})
+string(CONCAT GENERATED_KEYVALS ${GENERATED_KEYVALS})
+
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/module_list.c.in ${CMAKE_CURRENT_BINARY_DIR}/${CFE_PSP_TARGETNAME}_module_list.c @ONLY)
 
 add_library(psp-${CFE_PSP_TARGETNAME} STATIC
@@ -60,7 +63,7 @@ target_link_libraries(psp-${CFE_PSP_TARGETNAME} PRIVATE
     psp_module_api
 )
 
-target_include_directories(psp-${CFE_PSP_TARGETNAME} INTERFACE 
+target_include_directories(psp-${CFE_PSP_TARGETNAME} INTERFACE
     fsw/inc
 )
 

README.md

@@ -9,6 +9,17 @@ This is a collection of APIs abstracting platform specific functionality to be l
 
 ## Version History
 
+
+### Development Build: v1.5.0-rc1+dev112
+
+- Cleans up stale code from the previous methods of generating 1Hz. Adds a new PSP module that instantiates an OSAL abstract timebase for use with cFE services. This single module is used across all psp implementations (mcp750, pc-linux, pc-rtems). Results in 1Hz timing tick on MCP750 will be more accurate. No changes to Linux or RTEMS
+- Fixes segfaults when `CFE_PSP_Port` routines are invoked on Linux.
+- Converts `cfe_psp_ram.c` and `cfe_psp_port.c` into modular components and removes from the "shared" directory. The existing implementations become the corresponding "direct" module, and are enabled based on the psp module selection. Adds a "notimpl" variant where all the functions return `CFE_PSP_ERR_NOT_IMPLEMENTED`. This is used on Linux
+or any other system where direct access is not possible.  Renames the existing `eeprom_stub` module to be `eeprom_notimpl` for consistency and to avoid confusion with the unit test stubs.
+- Implements two PSP modules to provide `CFE_PSP_GetTime` and `CFE_PSP_GetTimeBase`, one for POSIX-compliant RTOS using `clock_gettime()` and the other specifically for PowerPC processors on VxWorks that have the `vxTimeBaseGet()` routine. Clarifies and documents the difference and use cases for `CFE_PSP_GetTime` and `CFE_PSP_GetTimeBase`. No impact to behavior.
+- Adds a coverage test for the VxWorks PSP timebase module and provides an example of how this can be implemented for other modules.
+- See <https://github.com/nasa/PSP/pull/289> and <https://github.com/nasa/cFS/pull/238>
+
 ### Development Build: v1.5.0-rc1+dev101
 
 - Removes unnecessary global config structure `Target_PspConfigData` and associated elements infavor of the new version API.

fsw/inc/cfe_psp.h

@@ -146,6 +146,13 @@
 #define CFE_PSP_RST_SUBTYPE_MAX 10
 /** \} */
 
+/**
+ * \brief The name of the software/RTOS timebase for general system timers.
+ *
+ * This name may be referred to by CFE TIME and/or SCH when setting up its own timers.
+ */
+#define CFE_PSP_SOFT_TIMEBASE_NAME "cFS-Master"
+
 /*
 ** Type Definitions
 */
@@ -166,10 +173,26 @@ extern void CFE_PSP_Main(void);
 ** The flight software (i.e. cFE ) should not call this routine.
 */
 
+/**
+ * \brief Sample/Read a monotonic platform clock with normalization
+ *
+ * Outputs an OS_time_t value indicating the time elapsed since an epoch.  The
+ * epoch is not defined, but typically represents the system boot time.  The
+ * value increases continously over time and cannot be reset by software.
+ *
+ * This is similar to the CFE_PSP_Get_Timebase(), but additionally it normalizes
+ * the output value to an OS_time_t, thereby providing consistent units to
+ * the calling application.  Any OSAL-provided routine accepts OS_time_t inputs
+ * may be used to convert this value into other standardized time units.
+ *
+ * \note This should refer to the same time domain as CFE_PSP_Get_Timebase(),
+ * the primary difference being the format and units of the output value.
+ *
+ * \sa CFE_PSP_Get_Timebase()
+ *
+ * \param[out] LocalTime Value of PSP tick counter as OS_time_t
+ */
 extern void CFE_PSP_GetTime(OS_time_t *LocalTime);
-/* This call gets the local time from the hardware on the Vxworks system
- * on the mcp750s
- * on the other os/hardware setup, it will get the time the normal way */
 
 extern void CFE_PSP_Restart(uint32 resetType);
 /*
@@ -229,10 +252,31 @@ extern uint32 CFE_PSP_GetTimerLow32Rollover(void);
 ** CFE_PSP_TIMER_LOW32_ROLLOVER will be 0.
 */
 
+/**
+ * \brief Sample/Read a monotonic platform clock without normalization
+ *
+ * This is defined as a free-running, monotonically-increasing tick counter.  The
+ * epoch is not defined, but typically is the system boot time, and the value increases
+ * indefinitely as the system runs.  The tick period/rate is also not defined.
+ *
+ * Rollover events - where the range of representable values is exceeded - are
+ * theoretically possible, but would take many years of continuous uptime to occur
+ * (typically hundreds of years, if not thousands). System designers should ensure
+ * that the actual tick rate and resulting timebase range is sufficiently large to
+ * ensure that rollover is not a concern.
+ *
+ * \note This is a "raw" value from the underlying platform with minimal/no conversions
+ * or normalization applied.  Neither the epoch nor the resolution of this tick
+ * counter is specified, and it may vary from platform to platform.  Use the
+ * CFE_PSP_GetTime() function to sample the timebase and also convert the units
+ * into a normalized/more consistent form.
+ *
+ * \sa CFE_PSP_GetTime()
+ *
+ * \param[out] Tbu Buffer to hold the upper 32 bits of a 64-bit tick counter
+ * \param[out] Tbl Buffer to hold the lower 32 bits of a 64-bit tick counter
+ */
 extern void CFE_PSP_Get_Timebase(uint32 *Tbu, uint32 *Tbl);
-/*
-** CFE_PSP_Get_Timebase
-*/
 
 extern uint32 CFE_PSP_Get_Dec(void);
 /*

fsw/mcp750-vxworks/CMakeLists.txt

@@ -14,7 +14,6 @@ add_library(psp-${CFE_PSP_TARGETNAME}-impl OBJECT
     src/cfe_psp_ssr.c
     src/cfe_psp_start.c
     src/cfe_psp_support.c
-    src/cfe_psp_timer.c
     src/cfe_psp_watchdog.c
 )
 target_compile_definitions(psp-${CFE_SYSTEM_PSPNAME}-impl PRIVATE

fsw/mcp750-vxworks/inc/cfe_psp_config.h

@@ -37,6 +37,23 @@
 #include "taskLib.h"
 #include "arch/ppc/esfPpc.h"
 
+/**
+ * \brief Period of the VxWorks timebase, in nanoseconds
+ *
+ * This is expressed as a ratio in case it is not a whole number.
+ *
+ * Multiplying the timebase register by 60 should yield a result
+ * in nanoseconds, and then further dividing by the OSAL OS_time_t tick
+ * resolution will convert to an OS_time_t compatible value.
+ *
+ * On the MCP750 - the PPC timebase runs at 60ns period or ~16.67 MHz.
+ *
+ * Note this is distinct from the VxWorks system timer tick which runs,
+ * confusingly, at 60Hz or a ~16.67ms period.
+ */
+#define CFE_PSP_VX_TIMEBASE_PERIOD_NUMERATOR   60
+#define CFE_PSP_VX_TIMEBASE_PERIOD_DENOMINATOR 1
+
 /*
 ** This define sets the number of memory ranges that are defined in the memory range defintion
 ** table.
@@ -51,6 +68,16 @@
  */
 #define CFE_PSP_MAX_EXCEPTION_ENTRIES 4
 
+/*
+ * The tick period that will be configured in the RTOS for the simulated
+ * time base, in microseconds.  This in turn is used to drive the 1hz clock
+ * and other functions.
+ *
+ * On the MCP750 the sysClockRate runs at 60Hz so this is the same period
+ * that the cFE software timebase will be configured at.
+ */
+#define CFE_PSP_SOFT_TIMEBASE_PERIOD 16666
+
 /*
 ** Typedef for the layout of the vxWorks boot record structure
 **

fsw/mcp750-vxworks/inc/psp_version.h

@@ -29,7 +29,7 @@
 /*
  * Development Build Macro Definitions
  */
-#define CFE_PSP_IMPL_BUILD_NUMBER   101
+#define CFE_PSP_IMPL_BUILD_NUMBER   112
 #define CFE_PSP_IMPL_BUILD_BASELINE "v1.5.0-rc1"
 
 /*

fsw/mcp750-vxworks/psp_module_list.cmake

@@ -1,4 +1,8 @@
-# This is a list of modules that is included as a fixed/base set 
+# This is a list of modules that is included as a fixed/base set
 # when this PSP is selected.  They must exist under fsw/modules
 
+soft_timebase
+timebase_vxworks
 eeprom_direct
+ram_direct
+port_direct

fsw/mcp750-vxworks/src/cfe_psp_start.c

@@ -59,6 +59,7 @@
 
 #include "cfe_psp.h"
 #include "cfe_psp_memory.h"
+#include "cfe_psp_module.h"
 
 /*
 **  External Declarations
@@ -74,7 +75,6 @@ IMPORT void sysPciWrite32(UINT32, UINT32);
 
 #define CFE_PSP_MAIN_FUNCTION       (*GLOBAL_CONFIGDATA.CfeConfig->SystemMain)
 #define CFE_PSP_NONVOL_STARTUP_FILE (GLOBAL_CONFIGDATA.CfeConfig->NonvolStartupFile)
-#define CFE_PSP_1HZ_FUNCTION        (*GLOBAL_CONFIGDATA.CfeConfig->System1HzISR)
 
 /******************************************************************************
 **  Function:  OS_Application_Startup()
@@ -146,6 +146,11 @@ void OS_Application_Startup(void)
     */
     CFE_PSP_SetupReservedMemoryMap();
 
+    /*
+    ** Initialize the statically linked modules (if any)
+    */
+    CFE_PSP_ModuleInit();
+
     /*
     ** Determine Reset type by reading the hardware reset register.
     */
@@ -232,30 +237,3 @@ void OS_Application_Startup(void)
     */
     CFE_PSP_MAIN_FUNCTION(reset_type, reset_subtype, 1, CFE_PSP_NONVOL_STARTUP_FILE);
 }
-
-/******************************************************************************
-**  Function:  OS_Application_Run()
-**
-**  Purpose:
-**    Idle Loop entry point from OSAL BSP.
-**
-**  Arguments:
-**    (none)
-**
-**  Return:
-**    (none)
-*/
-void OS_Application_Run(void)
-{
-    int TicksPerSecond;
-
-    /*
-    ** Main loop for default task and simulated 1hz
-    */
-    for (;;)
-    {
-        TicksPerSecond = sysClkRateGet();
-        (void)taskDelay(TicksPerSecond);
-        CFE_PSP_1HZ_FUNCTION();
-    }
-}