Fix nasa#266, psp module to implement timebase

Clarifies the use case for CFE_PSP_GetTime and CFE_PSP_GetTimeBase.

Moves the implementation of these to separate PSP modules, so MCP750
on VxWorks can use the optimized vxTimeBaseGet() routine while
Linux and RTEMS can use the generic posix CLOCK_MONOTONIC.

fsw/inc/cfe_psp.h

@@ -185,10 +185,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);
 /*
@@ -248,10 +264,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

@@ -15,7 +15,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.

fsw/mcp750-vxworks/psp_module_list.cmake

@@ -1,4 +1,5 @@
 # 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
 
+timebase_vxworks
 eeprom_direct

fsw/modules/timebase_posix_clock/CMakeLists.txt

@@ -0,0 +1,3 @@
+
+# Create the module
+add_psp_module(timebase_posix_clock cfe_psp_timebase_posix_clock.c)